oktest 1.0.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c60ec7ce654d0f50f7f2cb6523e2f27f4e843b7e88e37d886a694553805f2d7e
-  data.tar.gz: 559d192eaa5a321a59db95defbc2e7e4ec271bc8d3b97aeba2b8658a61a1b0d9
+  metadata.gz: 5232c4c9a9bf78763791cf182129900a376d1dd619fbf4a21f441ea10c0a7f27
+  data.tar.gz: 1d35a5ec4678e1a80624c058a32647cc6013c6a3dc4f87f3590bea2a226ea412
 SHA512:
-  metadata.gz: 73e39ea5796c682696127b34bff655870458b509aec487b2420276e8bd892a6a60c82a74895c0be89aa2160a231ef08eb92aff8b5a998ca335e735efbb410487
-  data.tar.gz: 8795c2227f46c7137d3456fa1040aaff0de3d020748c553439d39c7852a66cd0af7d81150cd26ef4c68907d503501de5c7cd3ec3eb3bfa6bdfe1bf2e4c9d5435
+  metadata.gz: 385ddc6a48f39657c38ee43ade9c89677aa686f8e7f55ec90eb9aef7d9dbec795cea55014e48070a22a18b63daea081863a4c6c0afc3c1d24c33316a70fcd149
+  data.tar.gz: ea3d7947b5195db3cdfd7a435adbdf0d96edfcfc0a653b67d7a241d4dec3e479c986fe8fc8294427e3c05343681b2308474131a35e5e62b75d1214660e62599e

data/README.md

@@ -4,12 +4,13 @@
 
 Oktest.rb is a new-style testing library for Ruby.
 
-* `ok {actual} == expected` style assertion.
-* **Fixture injection** inspired by dependency injection.
+* `ok {actual} == expected` style [assertion](#assertions).
+* [Fixture injection](#fixture-injection) inspired by dependency injection.
 * Structured test specifications like RSpec.
-* Filtering testcases by pattern or tags.
+* [JSON Matcher](#json-matcher) similar to JSON Schema.
+* [Filtering](#tag-and-filtering) testcases by pattern or tags.
 * Blue/red color instead of green/red for accesability.
-* Small code size (about 2400 lines) and good performance.
+* Small code size (less than 3000 lines) and good performance.
 
 ```ruby
 ### Oktest                           ### Test::Unit
@@ -54,7 +55,7 @@ Oktest.rb requires Ruby 2.3 or later.
     * <a href="#install">Install</a>
     * <a href="#basic-example">Basic Example</a>
     * <a href="#assertion-failure-and-error">Assertion Failure, and Error</a>
-    * <a href="#skip-and-todo">Skip, and Todo</a>
+    * <a href="#skip-and-todo">Skip and Todo</a>
     * <a href="#reporting-style">Reporting Style</a>
     * <a href="#run-all-test-scripts-under-directory">Run All Test Scripts Under Directory</a>
     * <a href="#tag-and-filtering">Tag and Filtering</a>
@@ -82,6 +83,11 @@ Oktest.rb requires Ruby 2.3 or later.
     * <a href="#dummy_attrs"><code>dummy_attrs()</code></a>
     * <a href="#dummy_ivars"><code>dummy_ivars()</code></a>
     * <a href="#recorder"><code>recorder()</code></a>
+  * <a href="#json-matcher">JSON Matcher</a>
+    * <a href="#simple-example">Simple Example</a>
+    * <a href="#nested-example">Nested Example</a>
+    * <a href="#complex-example">Complex Example</a>
+    * <a href="#helper-methods-for-json-matcher">Helper Methods for JSON Matcher</a>
   * <a href="#tips">Tips</a>
     * <a href="#ok--in-minitest"><code>ok {}</code> in MiniTest</a>
     * <a href="#testing-rack-application">Testing Rack Application</a>
@@ -165,6 +171,7 @@ Result:
 
 ```terminal
 $ oktest test/example01_test.rb   # or: ruby test/example01_test.rb
+## test/example01_test.rb
 * Hello
   * #hello()
     - [pass] returns greeting message.
@@ -172,6 +179,10 @@ $ oktest test/example01_test.rb   # or: ruby test/example01_test.rb
 ## total:2 (pass:2, fail:0, error:0, skip:0, todo:0) in 0.000s
 ```
 
+For accessibility reason, Oktest.rb prints passed test cases in blue color
+instead of green color.
+See https://accessibility.psu.edu/color/colorcoding/#RB for details.
+
 
 ### Assertion Failure, and Error
 
@@ -202,19 +213,20 @@ Result:
 
 ```terminal
 $ oktest test/example02_test.rb   # or: ruby test/example02_test.rb
+## test/example02_test.rb
 * other examples
   - [Fail] example of assertion failure
   - [ERROR] example of something error
 ----------------------------------------------------------------------
 [Fail] other examples > example of assertion failure
-    tmp/test/example02_test.rb:9:in `block (3 levels) in <main>'
+    test/example02_test.rb:9:in `block (3 levels) in <main>'
         ok {1+1} == 0     # FAIL
 $<actual> == $<expected>: failed.
     $<actual>:   2
     $<expected>: 0
 ----------------------------------------------------------------------
 [ERROR] other examples > example of something error
-    tmp/test/example02_test.rb:13:in `block (3 levels) in <main>'
+    test/example02_test.rb:13:in `block (3 levels) in <main>'
         x = foobar        # NameError
 NameError: undefined local variable or method `foobar' for #<#<Class:...>:...>
 ----------------------------------------------------------------------
@@ -222,7 +234,7 @@ NameError: undefined local variable or method `foobar' for #<#<Class:...>:...>
 ```
 
 
-### Skip, and Todo
+### Skip and Todo
 
 test/example03_test.rb:
 
@@ -256,6 +268,7 @@ Result:
 
 ```terminal
 $ oktest test/example03_test.rb   # or: ruby test/example03_test.rb
+## oktest test/example03_test.rb
 * other examples
   - [Skip] example of skip (reason: requires Ruby3)
   - [TODO] example of todo
@@ -276,6 +289,7 @@ Verbose mode (default):
 
 ```terminal
 $ oktest test/example01_test.rb -s verbose  # or -sv
+## test/example01_test.rb
 * Hello
   * #hello()
     - [pass] returns greeting message.
@@ -287,6 +301,16 @@ Simple mode:
 
 ```terminal
 $ oktest test/example01_test.rb -s simple   # or -ss
+## test/example01_test.rb
+* Hello: 
+  * #hello(): ..
+## total:2 (pass:2, fail:0, error:0, skip:0, todo:0) in 0.000s
+```
+
+Compact mode:
+
+```terminal
+$ oktest test/example01_test.rb -s compact  # or -sc
 test/example01_test.rb: ..
 ## total:2 (pass:2, fail:0, error:0, skip:0, todo:0) in 0.000s
 ```
@@ -294,7 +318,7 @@ test/example01_test.rb: ..
 Plain mode:
 
 ```terminal
-$ oktest test/example01_test.rb -s simple   # or -ss
+$ oktest test/example01_test.rb -s plain    # or -sp
 ..
 ## total:2 (pass:2, fail:0, error:0, skip:0, todo:0) in 0.000s
 ```
@@ -311,21 +335,23 @@ Quiet mode reports progress only of failed or error test cases (and doesn't
 report progress of passed ones), so it's output is very compact. This is
 very useful for large project which contains large number of test cases.
 
+(Note: `ruby test/example01_test.rb -s <STYLE>` is also available.)
+
 
 ### Run All Test Scripts Under Directory
 
 How to run test scripts under `test` directory:
 
 ```terminal
-$ ls test
+$ ls test/
 example01_test.rb       example02_test.rb       example03_test.rb
 
-$ oktest -s simple test  # or: ruby -r oktest -e 'Oktest.main' -- test -s simple
-tmp/test/example01_test.rb: ..
-tmp/test/example02_test.rb: fE
+$ oktest -s compact test  # or: ruby -r oktest -e 'Oktest.main' -- test -s compact
+test/example01_test.rb: ..
+test/example02_test.rb: fE
 ----------------------------------------------------------------------
 [Fail] other examples > example of assertion failure
-    tmp/test/example02_test.rb:9:in `block (3 levels) in <top (required)>'
+    test/example02_test.rb:9:in `block (3 levels) in <top (required)>'
         ok {1+1} == 0     # FAIL
     -e:1:in `<main>'
 $<actual> == $<expected>: failed.
@@ -333,12 +359,12 @@ $<actual> == $<expected>: failed.
     $<expected>: 0
 ----------------------------------------------------------------------
 [ERROR] other examples > example of something error
-    tmp/test/example02_test.rb:13:in `block (3 levels) in <top (required)>'
+    test/example02_test.rb:13:in `block (3 levels) in <top (required)>'
         x = foobar        # NameError
     -e:1:in `<main>'
 NameError: undefined local variable or method `foobar' for #<#<Class:...>:...>
 ----------------------------------------------------------------------
-tmp/test/example03_test.rb: st
+test/example03_test.rb: st
 ## total:6 (pass:2, fail:1, error:1, skip:1, todo:1) in 0.000s
 ```
 
@@ -348,7 +374,8 @@ Test script filename should be `test_xxx.rb` or `xxx_test.rb`
 
 ### Tag and Filtering
 
-`topic()` and `spec()` accepts tag name, for example 'obsolete' or 'experimental'.
+`scope()`, `topic()`, and `spec()` accepts tag name, for example 'obsolete'
+or 'experimental'.
 
 test/example04_test.rb:
 
@@ -388,16 +415,16 @@ Oktest.scope do
 end
 ```
 
-It is possible to filter topics and specs by tag name (pattern).
+It is possible to filter topics and specs by tag name or pattern.
+Pattern (!= regular expression) supports `*`, `?`, `[]` and `{}`.
 
 ```terminal
-$ oktest -F tag=exp         tests/     # filter by tag name
-$ oktest -F tag='*exp*'     tests/     # filter by tag name pattern
-$ oktest -F tag='{exp,old}' tests/     # filter by multiple tag names
+$ oktest -F tag=exp         test/      # filter by tag name
+$ oktest -F tag='*exp*'     test/      # filter by tag name pattern
+$ oktest -F tag='{exp,old}' test/      # filter by multiple tag names
 ```
 
 It is also possible to filter topics or specs by name.
-Pattern (!= regular expression) supports `*`, `?`, `[]`, and `{}`.
 
 ```terminal
 $ oktest -F topic='*Integer*' test/    # filter topics by pattern
@@ -407,8 +434,8 @@ $ oktest -F spec='*#[1-3]'    test/    # filter specs by pattern
 If you need negative filter, use `!=` instead of `=`.
 
 ```terminal
-$ oktest -F spec!='*#5'      tests/    # exclude spec 'example #5'
-$ oktest -F tag!='{exp,old}' tests/    # exclude tag='exp' or tag='old'
+$ oktest -F spec!='*#5'      test/     # exclude spec 'example #5'
+$ oktest -F tag!='{exp,old}' test/     # exclude tag='exp' or tag='old'
 ```
 
 
@@ -452,6 +479,7 @@ Result:
 
 ```terminal
 $ ruby test/example05_test.rb
+## test/example05_test.rb
 * Integer
   * #abs()
     - When value is negative...
@@ -466,7 +494,7 @@ $ ruby test/example05_test.rb
 
 ### Optional: Unary Operators
 
-`topic()` accepts unary `+` operator and `spec()` accepts unary `-` operator.
+`topic()` accepts unary plus (`+`) and `spec()` accepts unary minus (`-`).
 This makes test scripts more readable.
 
 <!--
@@ -500,7 +528,7 @@ end
 
 ### Generate Test Code Skeleton
 
-`oktest -G` (or `oktest --generate`) generates test code skeleton from ruby file.
+`oktest --generate` (or `oktest -G`) generates test code skeleton from ruby file.
 Comment line starting with `#;` is regarded as spec description.
 
 hello.rb:
@@ -523,7 +551,7 @@ end
 Generate test code skeleton:
 
 ```terminal
-$ oktest -G hello.rb > test/hello_test.rb
+$ oktest --generate hello.rb > test/hello_test.rb
 ```
 
 test/hello_test.rb:
@@ -608,7 +636,7 @@ Oktest.scope do
     end
 
     spec "example" do
-      s = hello()               # call method in spec block
+      s = hello()               # call it in spec block
       ok {s} == "Hello!"
     end
 
@@ -701,7 +729,7 @@ ok {a}.item(key, e)      # alias of `ok {a}.keyval(key, e)`
 ok {a}.length(e)         # fail unless a.length == e
 ```
 
-It is possible to chan method call of `.attr()` and `.keyval()`.
+It is possible to chain method call of `.attr()` and `.keyval()`.
 
 <!--
 test/example11b_test.rb:
@@ -873,7 +901,7 @@ end
 ```
 
 To catch subclass of error class, invoke `.raise!` instead of `.raise?`.
-For example: `ok {pr}.raise!(NameError, /foobar/, subclass: true)`.
+For example: `ok {pr}.raise!(NameError, /foobar/)`.
 
 <!--
 test/example14f_test.rb:
@@ -1017,8 +1045,8 @@ Oktest.scope do
         after  { puts "===== Inner: after =====" }  # !!!!!
 
         spec "example" do
-	  ok {1+1} == 2
-	end
+          ok {1+1} == 2
+        end
 
       end
 
@@ -1075,7 +1103,7 @@ Oktest.scope do
 end
 ```
 
-* `at_end()` can be called multiple times.
+* `at_end()` can be called multiple times in a spec.
 * Registered blocks are invoked in reverse order at end of test case.
 * Registered blocks of `at_end()` are invoked prior to block of `after()`.
 * If something error raised in `at_end()`, test script execution will be
@@ -1085,7 +1113,7 @@ end
 ### Named Fixtures
 
 `fixture() { ... }` in topic or scope block defines fixture builder,
-and `fixture()` in scope block returns fixture data.
+and `fixture()` in spec block returns fixture data.
 
 test/example23_test.rb:
 
@@ -1144,7 +1172,7 @@ Oktest.scope do
 end
 ```
 
-* Fixtures can be defined in block of `topic()` as well as block of `Object.scope()`.
+* Fixture builders can be defined in `topic()` block as well as `Oktest.scope()` block.
 * If fixture requires clean-up operation, call `at_end()` in `fixture()` block.
 
 ```ruby
@@ -1267,7 +1295,7 @@ Oktest.scope do
 end
 ```
 
-* First argument of `capture_sio()` represents data from `$stdin`.
+* The first argument of `capture_sio()` represents data from `$stdin`.
   If it is not necessary, you can omit it like `caputre_sio() do ... end`.
 * If you need `$stdin.tty? == true` and `$stdout.tty? == true`,
   call `capture_sio(tty: true) do ... end`.
@@ -1275,7 +1303,7 @@ end
 
 ### `dummy_file()`
 
-`dummy_file()` creates dummy file temporarily.
+`dummy_file()` creates a dummy file temporarily.
 
 test/example32_test.rb:
 
@@ -1310,12 +1338,12 @@ Oktest.scope do
 end
 ```
 
-* If first argument of `dummy_file()` is nil, then it generates temporary file name automatically.
+* If the first argument of `dummy_file()` is nil, then it generates temporary file name automatically.
 
 
 ### `dummy_dir()`
 
-`dummy_dir()` creates dummy directory temporarily.
+`dummy_dir()` creates a dummy directory temporarily.
 
 test/example33_test.rb:
 
@@ -1352,7 +1380,7 @@ Oktest.scope do
 end
 ```
 
-* If first argument of `dummy_dir()` is nil, then it generates temorary directory name automatically.
+* If the first argument of `dummy_dir()` is nil, then it generates temorary directory name automatically.
 
 
 ### `dummy_values()`
@@ -1519,7 +1547,7 @@ end
 
 ### `recorder()`
 
-`recorder()` returns Benry::Recorder object.
+`recorder()` returns `Benry::Recorder` object.
 See [Benry::Recorder README](https://github.com/kwatch/benry-ruby/blob/ruby/benry-recorder/README.md)
 for detals.
 
@@ -1584,6 +1612,216 @@ end
 
 
 
+## JSON Matcher
+
+Oktest.rb provides easy way to assert JSON data.
+This is very convenient feature, but don't abuse it.
+
+
+### Simple Example
+
+<!--
+test/example41_test.rb:
+-->
+```ruby
+require 'oktest'
+require 'set'                               # !!!!!
+
+Oktest.scope do
+  topic 'JSON Example' do
+
+    spec "simple example" do
+      actual = {
+        "name":     "Alice",
+        "id":       1001,
+        "age":      18,
+        "email":    "alice@example.com",
+        "gender":   "F",
+        "deleted":  false,
+        "tags":     ["aaa", "bbb", "ccc"],
+       #"twitter":  "@alice",
+      }
+      ## assertion
+      ok {JSON(actual)} === {               # requires `JSON()` and `===`
+        "name":     "Alice",                # scalar value
+        "id":       1000..9999,             # range object
+        "age":      Integer,                # class object
+        "email":    /^\w+@example\.com$/,   # regexp
+        "gender":   Set.new(["M", "F"]),    # Set object ("M" or "F")
+        "deleted":  Set.new([true, false]), # boolean (true or false)
+        "tags":     [/^\w+$/].each,         # Enumerator object (!= Array obj)
+        "twitter?": /^@\w+$/,               # key 'xxx?' means optional value
+      }
+    end
+
+  end
+end
+```
+
+(Note: Ruby 2.4 or older doesn't have `Set#===()`, so above code will occur error
+ in Ruby 2.4 or older. Please add the folllowing hack in your test script.)
+
+```ruby
+require 'set'
+unless Set.instance_methods(false).include?(:===)  # for Ruby 2.4 or older
+  class Set; alias === include?; end
+end
+```
+
+Notice that `Enumerator` has different meaning from `Array` in JSON matcher.
+
+```ruby
+  actual = {"tags": ["foo", "bar", "baz"]}
+
+  ## Array
+  ok {JSON(actual)} == {"tags": ["foo", "bar", "baz"]}
+
+  ## Enumerator
+  ok {JSON(actual)} == {"tags": [/^\w+$/].each}
+```
+
+
+### Nested Example
+
+<!--
+test/example42_test.rb:
+-->
+```ruby
+require 'oktest'
+require 'set'                            # !!!!!
+
+Oktest.scope do
+  topic 'JSON Example' do
+
+    spec "nested example" do
+      actual = {
+        "teams": [
+          {
+            "team": "Section 9",
+            "members": [
+              {"id": 2500, "name": "Aramaki", "gender": "M"},
+              {"id": 2501, "name": "Motoko" , "gender": "F"},
+              {"id": 2502, "name": "Batou"  , "gender": "M"},
+            ],
+            "leader": "Aramaki",
+          },
+          {
+            "team": "SOS Brigade",
+            "members": [
+              {"id": 1001, "name": "Haruhi", "gender": "F"},
+              {"id": 1002, "name": "Mikuru", "gender": "F"},
+              {"id": 1003, "name": "Yuki"  , "gender": "F"},
+              {"id": 1004, "name": "Itsuki", "gender": "M"},
+              {"id": 1005, "name": "Kyon"  , "gender": "M"},
+            ],
+          },
+        ],
+      }
+      ## assertion
+      ok {JSON(actual)} === {            # requires `JSON()` and `===`
+        "teams": [
+          {
+            "team": String,
+            "members": [
+              {"id": 1000..9999, "name": String, "gender": Set.new(["M", "F"])}
+            ].each,                     # Enumerator object (!= Array obj)
+            "leader?": String,           # key 'xxx?' means optional value
+          }
+        ].each,                          # Enumerator object (!= Array obj)
+      }
+    end
+
+  end
+end
+```
+
+
+### Complex Example
+
+* `OR(x, y, z)` matches to `x`, `y`, or `z`.
+* `AND(x, y, z)` matches to `x`, `y`, and `z`.
+* Key `"*"` matches to any key of hash object.
+* `Any()` matches to anything.
+
+<!--
+test/example43_test.rb:
+-->
+```ruby
+require 'oktest'
+require 'set'
+
+Oktest.scope do
+  topic 'JSON Example' do
+
+    spec "OR() example" do
+      ok {JSON({"val": "123"})} === {"val": OR(String, Integer)}    # OR()
+      ok {JSON({"val":  123 })} === {"val": OR(String, Integer)}    # OR()
+    end
+
+    spec "AND() example" do
+      ok {JSON({"val": "123"})} === {"val": AND(String, /^\d+$/)}   # AND()
+      ok {JSON({"val":  123 })} === {"val": AND(Integer, 1..1000)}  # AND()
+    end
+
+    spec "`*` and `ANY` example" do
+      ok {JSON({"name": "Bob", "age": 20})} === {"*": Any()}    # '*' and Any()
+    end
+
+    spec "complex exapmle" do
+      actual = {
+        "item":   "awesome item",
+        "colors": ["red", "#cceeff", "green", "#fff"],
+        "memo":   "this is awesome.",
+        "url":    "https://example.com/awesome",
+      }
+      ## assertion
+      color_names = ["red", "blue", "green", "white", "black"]
+      color_pat   = /^\#[0-9a-fA-F]{3}([0-9a-fA-F]{3})?$/
+      ok {JSON(actual)} === {
+        "colors": [
+          AND(String, OR(Set.new(color_names), color_pat)),   # AND() and OR()
+        ].each,
+        "*": Any(),             # match to any key (`"*"`) and value (`ANY`)
+      }
+    end
+
+  end
+end
+```
+
+(Note: `/^\d+$/` implies String value, and `1..100` implies Integer value.)
+
+```ruby
+## No need to write:
+##   ok {JSON{...}} === {"val": AND(String, /^\d+$/)}
+##   ok {JSON{...}} === {"val": AND(Integer, 1..100)}
+ok {JSON({"val": "A"})} === {"val": /^\d+$/}   # implies String value
+ok {JSON({"val": 99 })} === {"val": 1..100}    # implies Integer value
+```
+
+
+### Helper Methods for JSON Matcher
+
+Oktest.rb provides some helper methods and objects:
+
+* `Enum(x, y, z)` is almost same as `Set.new([x, y, z])`.
+* `Bool()` is same as `Enum(true, false)`.
+* `Length(3)` matches to length 3, and `Length(1..3)` matches to length 1..3.
+
+<!--
+test/example44_test.rb:
+-->
+```ruby
+  actual = {"gender": "M", "deleted": false, "code": "ABCD1234"}
+  ok {JSON(actual)} == {
+    "gender":  Enum("M", "F"),        # same as Set.new(["M", "F"])
+    "deleted": Bool(),                # same as Enum(true, false)
+    "code":    Length(6..10),         # code length should be 6..10
+  }
+```
+
+
+
 ## Tips
 
 
@@ -1592,7 +1830,7 @@ end
 If you want to use `ok {actual} == expected` style assertion in MiniTest,
 install `minitest-ok` gem instead of `otest` gem.
 
-test/example41_test.rb:
+test/example51_test.rb:
 
 ```ruby
 require 'minitest/spec'
@@ -1615,7 +1853,7 @@ See [minitest-ok README](https://github.com/kwatch/minitest-ok) for details.
 
 `rack-test_app` gem will help you to test Rack application very well.
 
-test/example42_test.rb:
+test/example52_test.rb:
 
 ```ruby
 require 'rack'
@@ -1648,7 +1886,7 @@ Oktest.scope do
 end
 ```
 
-Defining helper method per topic may help you.
+Defining helper methods per topic may help you.
 
 ```ruby
 $http = http                                   # !!!!
@@ -1688,7 +1926,7 @@ end
 
 Oktest.rb provides `Traverser` class which implements Visitor pattern.
 
-test/example44_test.rb:
+test/example54_test.rb:
 
 ```ruby
 require 'oktest'
@@ -1745,8 +1983,8 @@ MyTraverser.new.start()
 Result:
 
 ```terminal
-$ ruby test/example44_test.rb
-# scope: test/example44_test.rb
+$ ruby test/example54_test.rb
+# scope: test/example54_test.rb
   + topic: Example Topic
     - spec: sample #1
     - spec: sample #2
@@ -1826,10 +2064,8 @@ ruby run_all.rb | tail -5
 
 ### `--faster` Option
 
-`ok {}` is slightly slower than `assert()` in MiniTest.
-In almost case, you don't need to care about it.  But if you are working in
-very larget project and you want to run test scripts as fast as possible,
-try `--faster` option of `oktest` command.
+If you are working in very larget project and you want to run test scripts
+as fast as possible, try `--faster` option of `oktest` command.
 
 ```terminal
 $ oktest -s quiet --faster test/        ## only for very large project