oktest 1.0.2 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 9f8f2b588e8b3d85d2dfc1bbf975b491484b400a
-  data.tar.gz: 7b8ede816f90a30f76263b713456fb90ae1e86b5
+SHA256:
+  metadata.gz: 240a20810f76b97272c48007e0a8a3193f0217c0aa31d7e9ccf363e05aa577aa
+  data.tar.gz: 035ac9fb077d8f5e67355c9d6a177e67684e11e46db351edc71992f280d4ab08
 SHA512:
-  metadata.gz: 2888eb6c1bfde26a01bd15baaf40b5de1cfd0d6b604e9a6645dd778dc69412d92c3c89cb37abb7f73b94ac7adcaf151600b1ef17a5a89d253eb8f40fecc4d07b
-  data.tar.gz: b22ff5554db672ee5d7d048acf45fd6428106763ebd6d1277eb49fe1d15cabd45927564de2fa602e58a53825d040bfb684473fdebc9de4ba8dbc7f500db9e7d2
+  metadata.gz: 333dea58ea3e17034bda9706a426fc63e089fda74ea2b2626915b635b3cdf5e72cce076823b22acb2d7390a189408adf0286eac89650a80939d057f51ba2ff09
+  data.tar.gz: 4136c2c8613ca829d0d72deb8c857995a482e19b0b9c7c282e9a45b3948b9ac3dced2ba665544a98c62d79260e3bbf2da231f577c4221fd23bd81087dea168cf

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
@@ -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.
@@ -206,6 +213,7 @@ 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
@@ -260,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
@@ -280,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.
@@ -291,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
 ```
@@ -298,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
 ```
@@ -324,7 +344,7 @@ How to run test scripts under `test` directory:
 $ 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
+$ oktest -s compact test  # or: ruby -r oktest -e 'Oktest.main' -- test -s compact
 test/example01_test.rb: ..
 test/example02_test.rb: fE
 ----------------------------------------------------------------------
@@ -457,6 +477,7 @@ Result:
 
 ```terminal
 $ ruby test/example05_test.rb
+## test/example05_test.rb
 * Integer
   * #abs()
     - When value is negative...
@@ -1022,8 +1043,8 @@ Oktest.scope do
         after  { puts "===== Inner: after =====" }  # !!!!!
 
         spec "example" do
-	  ok {1+1} == 2
-	end
+          ok {1+1} == 2
+        end
 
       end
 
@@ -1589,6 +1610,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
 
 
@@ -1597,7 +1828,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'
@@ -1620,7 +1851,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'
@@ -1693,7 +1924,7 @@ end
 
 Oktest.rb provides `Traverser` class which implements Visitor pattern.
 
-test/example44_test.rb:
+test/example54_test.rb:
 
 ```ruby
 require 'oktest'
@@ -1750,8 +1981,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

data/Rakefile.rb

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 
 ###
-### $Release: 1.0.2 $
+### $Release: 1.1.0 $
 ### $Copyright: copyright(c) 2011-2021 kuwata-lab.com all rights reserved $
 ### $License: MIT License $
 ###

data/lib/oktest.rb

@@ -1,16 +1,18 @@
 # -*- coding: utf-8 -*-
 
 ###
-### $Release: 1.0.2 $
+### $Release: 1.1.0 $
 ### $Copyright: copyright(c) 2011-2021 kuwata-lab.com all rights reserved $
 ### $License: MIT License $
 ###
 
+require 'set'
+
 
 module Oktest
 
 
-  VERSION = '$Release: 1.0.2 $'.split()[1]
+  VERSION = '$Release: 1.1.0 $'.split()[1]
 
 
   class OktestError < StandardError
@@ -114,6 +116,10 @@ module Oktest
 
     def ===(expected)
       __done()
+      #; [!mjh4d] raises error when combination of 'not_ok()' and matcher object.
+      if @bool == false && @actual.is_a?(Matcher)
+        raise OktestError, "negative `===` is not available with matcher object."
+      end
       #; [!42f6a] raises assertion error when failed.
       #; [!vhvyu] is avaialbe with NOT.
       __assert(@bool == (@actual === expected)) {
@@ -264,10 +270,10 @@ module Oktest
 
     def raise!(errcls=nil, errmsg=nil, &b)
       #; [!8k6ee] compares error class by '.is_a?' instead of '=='.
-      return raise?(errcls, errmsg, subclass: true, &b)
+      return raise?(errcls, errmsg, _subclass: true, &b)
     end
 
-    def raise?(errcls=nil, errmsg=nil, subclass: false, &b)
+    def raise?(errcls=nil, errmsg=nil, _subclass: false, &b)
       __done()
       #; [!2rnni] 1st argument can be error message string or rexp.
       if errmsg.nil? && ! errcls.nil? && ! (errcls.is_a?(Class) && errcls <= Exception)
@@ -289,8 +295,8 @@ module Oktest
           #; [!lq6jv] compares error class with '==' operator, not '.is_a?'.
           elsif exc.class == errcls    # not `exc.is_a?(errcls)`
             nil
-          #; [!hwg0z] compares error class with '.is_a?' if 'subclass: true' specified.
-          elsif subclass && exc.class < errcls
+          #; [!hwg0z] compares error class with '.is_a?' if '_subclass: true' specified.
+          elsif _subclass && exc.class < errcls
             nil
           #; [!4n3ed] reraises if exception is not matched to specified error class.
           else
@@ -328,8 +334,8 @@ module Oktest
           #; [!smprc] compares error class with '==' operator, not '.is_a?'.
           elsif exc.class == errcls    # not `exc.is_a?(errcls)`
             __assert(false) { "#{errcls.inspect} should not be raised but got #{exc.inspect}." }
-          #; [!34nd8] compares error class with '.is_a?' if 'subclass: true' specified.
-          elsif subclass && exc.class < errcls
+          #; [!34nd8] compares error class with '.is_a?' if '_subclass: true' specified.
+          elsif _subclass && exc.class < errcls
             __assert(false) { "#{errcls.inspect} should not be raised but got #{exc.inspect}." }
           #; [!shxne] reraises exception if different from specified error class.
           else
@@ -548,6 +554,246 @@ module Oktest
   end
 
 
+  class Matcher
+
+    def initialize(actual)
+      @actual = actual
+    end
+
+    def ===(expected)
+      #; [!spybn] raises NotImplementedError.
+      raise NotImplementedError.new("#{self.class.name}#===(): not implemented yet.")
+    end
+
+    def ==(expected)
+      #; [!ymt1b] raises OktestError.
+      raise OktestError, "JSON(): use `===` instead of `==`."
+    end
+
+    def fail(errmsg)
+      #; [!8qpsd] raises assertion error.
+      raise Oktest::FAIL_EXCEPTION, errmsg
+    end
+
+  end
+
+
+  class JsonMatcher < Matcher
+
+    def ===(expected)
+      #; [!4uf1o] raises assertion error when JSON not matched.
+      _compare([], @actual, expected)
+      #; [!0g0u4] returns true when JSON matched.
+      return true
+    end
+
+    private
+
+    def _compare?(path, a, e)
+      #; [!nkvqo] returns true when nothing raised.
+      #; [!57m2j] returns false when assertion error raised.
+      _compare(path, a, e)
+      return true
+    rescue FAIL_EXCEPTION
+      return false
+    end
+
+    def _compare(path, a, e)
+      if a.is_a?(Hash) && e.is_a?(Hash)
+        _compare_hash(path, a, e)
+      elsif a.is_a?(Array) && e.is_a?(Array)
+        _compare_array(path, a, e)
+      elsif e.is_a?(Enumerator)
+        _compare_enumerator(path, a, e)
+      elsif e.is_a?(OR)
+        _compare_or(path, a, e)
+      elsif e.is_a?(AND)
+        _compare_and(path, a, e)
+      else
+        _compare_value(path, a, e)
+      end
+    end
+
+    def _compare_value(path, a, e)
+      #; [!1ukbv] scalar value matches to integer, string, bool, and so son.
+      #; [!8o55d] class object matches to instance object.
+      #; [!s625d] regexp object matches to string value.
+      #; [!aqkk0] range object matches to scalar value.
+      #; [!a7bfs] Set object matches to enum value.
+      e === a  or fail <<"END"
+$<JSON>#{_path(path)}: $<expected> === $<actual> : failed.
+    $<actual>:   #{a.inspect}
+    $<expected>: #{e.inspect}
+END
+      #; [!4ymj2] fails when actual value is not matched to item class of range object.
+      if e.is_a?(Range)
+        expected_class = (e.begin || e.end).class
+        a.is_a?(expected_class)  or fail <<"END"
+$<JSON>#{_path(path)}: expected #{expected_class.name} value, but got #{a.class.name} value.
+    $<actual>:   #{a.inspect}
+    $<expected>: #{e.inspect}
+END
+      end
+    end
+
+    def _compare_array(path, a, e)
+      #; [!bz74w] fails when array lengths are different.
+      a.length == e.length  or fail <<"END"
+$<JSON>#{_path(path)}: $<actual>.length == $<expected>.length : failed.
+    $<actual>.length:   #{a.length}
+    $<expected>.length: #{e.length}
+    $<actual>:   #{a.inspect}
+    $<expected>: #{e.inspect}
+END
+      #; [!lh6d6] compares array items recursively.
+      path.push(nil)
+      i = -1
+      a.zip(e) do |a2, e2|
+        path[-1] = (i += 1)
+        _compare(path, a2, e2)
+      end
+      path.pop()
+    end
+
+    def _compare_hash(path, a, e)
+      #; [!rkv0z] compares two hashes with converting keys into string.
+      a2 = {}; a.each {|k, v| a2[k.to_s] = v }
+      e2 = {}; e.each {|k, v| e2[k.to_s] = v }
+      #; [!fmxyg] compares hash objects recursively.
+      path.push(nil)
+      a2.each_key do |k|
+        path[-1] = k
+        if e2.key?(k)
+          _compare(path, a2[k], e2[k])
+        #; [!jbyv6] key 'aaa?' represents optional key.
+        elsif e2.key?("#{k}?")
+          _compare(path, a2[k], e2["#{k}?"]) unless a2[k].nil?
+        #; [!uc4ag] key '*' matches to any key name.
+        elsif e2.key?("*")
+          _compare(path, a2[k], e2["*"])
+        #; [!mpbvu] fails when unexpected key exists in actual hash.
+        else
+          fail <<"END"
+$<JSON>#{_path(path)}: unexpected key.
+    $<actual>:   #{a2[k].inspect}
+END
+        end
+      end
+      path.pop()
+      #; [!4oasq] fails when expected key not exist in actual hash.
+      (e2.keys - a2.keys).each do |k|
+        k =~ /\?\z/ || k == "*"  or fail <<"END"
+$<JSON>#{_path(path)}: key \"#{k}\" expected but not found.
+    $<actual>.keys:   #{a2.keys.sort.inspect[1...-1]}
+    $<expected>.keys: #{e2.keys.sort.inspect[1...-1]}
+END
+      end
+    end
+
+    def _compare_enumerator(path, a, e)
+      #; [!ljrmc] fails when expected is an Enumerator object and actual is not an array.
+      e2 = e.first
+      a.is_a?(Array)  or fail <<"END"
+$<JSON>#{_path(path)}: Array value expected but got #{a.class.name} value.
+    $<actual>:   #{a.inspect}
+    $<expected>: [#{e2.inspect}].each
+END
+      #; [!sh5cg] Enumerator object matches to repeat of rule.
+      path.push(nil)
+      a.each_with_index do |a2, i|
+        path[-1] = i
+        _compare(path, a2, e2)
+      end
+      path.pop()
+    end
+
+    def _compare_or(path, a, e)
+      #; [!eqr3b] `OR()` matches to any of arguments.
+      #; [!5ybfg] `OR()` can contain `AND()`.
+      passed = e.items.any? {|e2| _compare?(path, a, e2) }
+      passed  or fail <<"END"
+$<JSON>#{_path(path)}: $<expected> === $<actual> : failed.
+    $<actual>:   #{a.inspect}
+    $<expected>: OR(#{e.items.collect(&:inspect).join(', ')})
+END
+    end
+
+    def _compare_and(path, a, e)
+      #; [!4hk96] `AND()` matches to all of arguments.
+      #; [!scx22] `AND()` can contain `OR()`.
+      failed = e.items.find {|e2| ! _compare?(path, a, e2) }
+      ! failed  or fail <<"END"
+$<JSON>#{_path(path)}: $<expected> === $<actual> : failed.
+    $<actual>:   #{a.inspect}
+    $<expected>: AND(#{failed.inspect})
+END
+    end
+
+    def _path(path)
+      #return path.collect {|x| "/#{x}" }.join()
+      return path.collect {|x| "[#{x.inspect}]" }.join()
+    end
+
+    protected
+
+    class OR
+      def initialize(*items)
+        @items = items
+      end
+      attr_reader :items
+      def inspect()
+        #; [!2mu33] returns 'OR(...)' string.
+        return "OR(#{@items.collect(&:inspect).join(', ')})"
+      end
+    end
+
+    class AND
+      def initialize(*items)
+        @items = items
+      end
+      attr_reader :items
+      def inspect()
+        #; [!w43ag] returns 'AND(...)' string.
+        return "AND(#{@items.collect(&:inspect).join(', ')})"
+      end
+    end
+
+    class Enum < Set
+      alias === include?     # Ruby 2.4 or older doesn't have 'Set#==='.
+      def inspect()
+        #; [!fam11] returns 'Enum(...)' string.
+        return "Enum(#{self.collect(&:inspect).join(', ')})"
+      end
+    end
+
+    class Length
+      def initialize(expected)
+        @expected = expected
+      end
+      def ===(actual)
+        #; [!03ozi] compares length of actual value with expected value.
+        return @expected === actual.length
+      end
+      def inspect()
+        #; [!nwv3e] returns 'Length(n)' string.
+        return "Length(#{@expected.inspect})"
+      end
+    end
+
+    class Any
+      def ===(actual)
+        #; [!mzion] returns true in any case.
+        true
+      end
+      def inspect()
+        #; [!6f0yv] returns 'Any()' string.
+        return "Any()"
+      end
+    end
+
+  end
+
+
   class Context
     ## * Context class is separated from ScopeNode, TopicNode, and SpecLeaf.
     ## * `topic()` and `spec()` creates subclass of Context class,
@@ -1116,6 +1362,41 @@ module Oktest
       return Benry::Recorder.new
     end
 
+    def JSON(actual)
+      #; [!n0k03] creates JsonMatcher object.
+      return JsonMatcher.new(actual)
+    end
+
+    def Enum(*values)
+      #; [!fbfr0] creates Enum object which is a subclass of Set.
+      return JsonMatcher::Enum.new(values)
+    end
+
+    def Bool()
+      #; [!vub5j] creates a set of true and false.
+      return Enum(true, false)
+    end
+
+    def OR(*args)
+      #; [!9e8im] creates `OR` object.
+      return JsonMatcher::OR.new(*args)
+    end
+
+    def AND(*args)
+      #; [!38jln] creates `AND` object.
+      return JsonMatcher::AND.new(*args)
+    end
+
+    def Length(n)
+      #; [!qqas3] creates Length object.
+      return JsonMatcher::Length.new(n)
+    end
+
+    def Any()
+      #; [!dlo1o] creates an 'Any' object.
+      return JsonMatcher::Any.new
+    end
+
   end
 
 
@@ -1215,11 +1496,25 @@ module Oktest
       @reporter.exit_all(self)
     end
 
+    def _spec_first(node)
+      a1, a2 = node.each_child.partition {|c|
+        c.is_a?(SpecLeaf) || (c.is_a?(TopicNode) && c._prefix != '*')
+      }
+      return a1+a2
+    end
+    private :_spec_first
+
     def visit_scope(scope, depth, parent)
       @reporter.enter_scope(scope) unless scope.equal?(THE_GLOBAL_SCOPE)
       #; [!5anr7] calls before_all and after_all blocks.
       call_before_all_block(scope)
-      scope.each_child {|c| c.accept_visitor(self, depth+1, scope) }
+      #; [!c5cw0] run specs and case_when in advance of specs and topics when SimpleReporter.
+      if @reporter.order_policy() == :spec_first
+        _spec_first(scope).each {|c| c.accept_visitor(self, depth+1, scope) }
+      else
+        scope.each_child {|c| c.accept_visitor(self, depth+1, scope) }
+      end
+      #
       call_after_all_block(scope)
       @reporter.exit_scope(scope) unless scope.equal?(THE_GLOBAL_SCOPE)
     end
@@ -1228,7 +1523,13 @@ module Oktest
       @reporter.enter_topic(topic, depth)
       #; [!i3yfv] calls 'before_all' and 'after_all' blocks.
       call_before_all_block(topic)
-      topic.each_child {|c| c.accept_visitor(self, depth+1, topic) }
+      #; [!p3a5o] run specs and case_when in advance of specs and topics when SimpleReporter.
+      if @reporter.order_policy() == :spec_first
+        _spec_first(topic).each {|c| c.accept_visitor(self, depth+1, topic) }
+      else
+        topic.each_child {|c| c.accept_visitor(self, depth+1, topic) }
+      end
+      #
       call_after_all_block(topic)
       @reporter.exit_topic(topic, depth)
     end
@@ -1429,6 +1730,7 @@ module Oktest
     def exit_spec(spec, depth, status, error, parent); end
     #
     def counts; {}; end
+    def order_policy(); nil; end     # :spec_first or nil
 
   end
 
@@ -1439,7 +1741,7 @@ module Oktest
     CHARS  = { :PASS=>'.', :FAIL=>'f', :ERROR=>'E', :SKIP=>'s', :TODO=>'t' }
 
 
-    def initialize
+    def initialize()
       @exceptions = []
       @counts = {}
     end
@@ -1582,6 +1884,10 @@ module Oktest
 
     LABELS = { :PASS=>'pass', :FAIL=>'Fail', :ERROR=>'ERROR', :SKIP=>'Skip', :TODO=>'TODO' }
 
+    def enter_scope(scope)
+      puts "## #{scope.filename}"
+    end
+
     def enter_topic(topic, depth)
       super
       puts "#{'  ' * (depth - 1)}#{topic._prefix} #{Color.topic(topic.target)}"
@@ -1615,6 +1921,64 @@ module Oktest
 
 
   class SimpleReporter < BaseReporter
+    #; [!jxa1b] reports topics and progress.
+
+    def initialize()
+      super
+      @_nl = true
+    end
+
+    def order_policy()
+      :spec_first
+    end
+
+    def _nl()
+      (puts(); @_nl = true) unless @_nl
+    end
+    private :_nl
+
+    def _nl_off()
+      @_nl = false
+    end
+    private :_nl_off
+
+    def enter_scope(scope)
+      _nl()
+      puts "## #{scope.filename}"
+    end
+
+    def exit_scope(scope)
+      _nl()
+      print_exceptions()
+    end
+
+    def enter_topic(topic, depth)
+      super
+      return if topic._prefix == '-'
+      _nl()
+      print "#{'  ' * (depth - 1)}#{topic._prefix} #{Color.topic(topic.target)}: "
+      $stdout.flush()
+      _nl_off()
+    end
+
+    def exit_topic(topic, depth)
+      super
+      return if topic._prefix == '-'
+      _nl()
+      print_exceptions()
+    end
+
+    def exit_spec(spec, depth, status, error, parent)
+      super
+      print Color.status(status, CHARS[status] || '?')
+      $stdout.flush
+      _nl_off()
+    end
+
+  end
+
+
+  class CompactReporter < BaseReporter
     #; [!xfd5o] reports filename.
 
     def enter_scope(scope)
@@ -1681,6 +2045,7 @@ module Oktest
   REPORTER_CLASSES = {
     'verbose' => VerboseReporter,  'v' => VerboseReporter,
     'simple'  => SimpleReporter,   's' => SimpleReporter,
+    'compact' => CompactReporter,  'c' => CompactReporter,
     'plain'   => PlainReporter,    'p' => PlainReporter,
     'quiet'   => QuietReporter,    'q' => QuietReporter,
   }
@@ -2185,7 +2550,8 @@ END
       Config.auto_run = false
       #; [!18qpe] runs test scripts.
       #; [!0qd92] '-s verbose' or '-sv' option prints test results in verbose mode.
-      #; [!ef5v7] '-s simple' or '-ss' option prints test results in simple mode.
+      #; [!zfdr5] '-s simple' or '-ss' option prints test results in simple mode.
+      #; [!ef5v7] '-s compact' or '-sc' option prints test results in compact mode.
       #; [!244te] '-s plain' or '-sp' option prints test results in plain mode.
       #; [!ai61w] '-s quiet' or '-sq' option prints test results in quiet mode.
       n_errors = Oktest.run(:style=>opts.style)
@@ -2246,7 +2612,7 @@ END
 Usage: %{command} [<options>] [<file-or-directory>...]
   -h, --help             : show help
       --version          : print version
-  -s <STYLE>             : report style (verbose/simple/plain/quiet, or v/s/p/q)
+  -s <REPORT-STYLE>      : verbose/simple/compact/plain/quiet, or v/s/c/p/q
   -F <PATTERN>           : filter topic or spec with pattern (see below)
       --color[={on|off}] : enable/disable output coloring forcedly
   -C, --create           : print test code skeleton