Synced with 1.18.

1 files changed, 78 insertions, 14 deletions

diff --git a/dragon/assert.rb b/dragon/assert.rb
index 0eb8c2a..0c26f29 100644
--- a/dragon/assert.rb
+++ b/dragon/assert.rb
@@ -4,13 +4,57 @@
 # assert.rb has been released under MIT (*only this file*).
 
 module GTK
+=begin
+This is a tiny assertion api for the unit testing portion of Game Toolkit.
+
+@example
+
+1. Create a file called tests.rb under mygame.
+2. Any method that begins with the word test_ will be considered a test.
+
+def test_this_works args, assert
+  assert.equal! 1, 1
+end
+
+3. To run a test, save the file while the game is running.
+
+@example
+
+To add an assertion open up this class and write:
+
+class Assert
+  def custom_assertion actual, expected, message = nil
+    # this tell Game Toolkit that an assertion was performed (so that the test isn't marked inconclusive).
+    @assertion_performed = true
+
+    # perform your custom logic here and rais an exception to denote a failure.
+
+    raise "Some Error. #{message}."
+  end
+end
+=end
   class Assert
     attr :assertion_performed
 
+=begin
+Us this if you are throwing your own exceptions and you want to mark the tests as ran (so that it wont be marked as inconclusive).
+=end
     def ok!
       @assertion_performed = true
     end
 
+=begin
+Assert if a value is a thruthy value. All assert method take an optional final parameter that is the message to display to the user.
+
+@example
+
+def test_does_this_work args, assert
+  some_result = Person.new
+  assert.true! some_result
+  # OR
+  assert.true! some_result, "Person was not created."
+end
+=end
     def true! value, message = nil
       @assertion_performed = true
       if !value
@@ -20,6 +64,16 @@ module GTK
       nil
     end
 
+=begin
+Assert if a value is a falsey value.
+
+@example
+
+def test_does_this_work args, assert
+  some_result = nil
+  assert.false! some_result
+end
+=end
     def false! value, message = nil
       @assertion_performed = true
       if value
@@ -29,16 +83,39 @@ module GTK
       nil
     end
 
+=begin
+Assert if two values are equal.
+
+@example
+
+def test_does_this_work args, assert
+  a = 1
+  b = 1
+  assert.equal! a, b
+end
+=end
     def equal! actual, expected, message = nil
       @assertion_performed = true
       if actual != expected
         actual_string = "#{actual}#{actual.nil? ? " (nil) " : " " }".strip
-        message = "actual: #{actual_string} did not equal expected: #{expected}.\n#{message}"
+        message = "actual:\n#{actual_string} did not equal\nexpected:\n#{expected}.\n#{message}"
         raise message
       end
       nil
     end
 
+=begin
+Assert if a value is explicitly nil (not false).
+
+@example
+
+def test_does_this_work args, assert
+  a = nil
+  b = false
+  assert.nil! a # this will pass
+  assert.nil! b # this will throw an exception.
+end
+=end
     def nil! value, message = nil
       @assertion_performed = true
       if !value.nil?
@@ -47,18 +124,5 @@ module GTK
       end
       nil
     end
-
-    def raises! exception_class, message = nil
-      @assertion_performed = true
-      begin
-        yield
-      rescue exception_class
-        return # Success
-      rescue Exception => e
-        raise "Expected #{exception_class.name} to be raised but instead #{e.class.name} was raised\n#{message}"
-      else
-        raise "Expected #{exception_class.name} to be raised but nothing was raised\n#{message}"
-      end
-    end
   end
 end