oktest 1.0.1 → 1.2.0

data/lib/oktest.rb

@@ -1,16 +1,18 @@
 # -*- coding: utf-8 -*-
 
 ###
-### $Release: 1.0.1 $
+### $Release: 1.2.0 $
 ### $Copyright: copyright(c) 2011-2021 kuwata-lab.com all rights reserved $
 ### $License: MIT License $
 ###
 
+require 'set'
+
 
 module Oktest
 
 
-  VERSION = '$Release: 1.0.1 $'.split()[1]
+  VERSION = '$Release: 1.2.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,261 @@ 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
+
+
+  module UtilHelper
+
+    def partial_regexp(pattern, begin_='\A', end_='\z', mark="{== ==}")
+      #; [!9drtn] is available in both topic and spec blocks.
+      return Util.partial_regexp(pattern, begin_, end_, mark)
+    end
+
+    def partial_regexp!(pattern, begin_='\A', end_='\z', mark="{== ==}")
+      #; [!wo4hp] is available in both topic and spec blocks.
+      return Util.partial_regexp!(pattern, begin_, end_, mark)
+    end
+
+  end
+
+
   class Context
     ## * Context class is separated from ScopeNode, TopicNode, and SpecLeaf.
     ## * `topic()` and `spec()` creates subclass of Context class,
@@ -555,6 +816,8 @@ module Oktest
     ## * `scope()` instanciates those subclasses, and run spec blocks
     ##    in that instance objects.
 
+    extend UtilHelper
+
     class << self
       attr_accessor :__node
     end
@@ -587,26 +850,29 @@ module Oktest
       return to
     end
 
-    def self.spec(desc, tag: nil, &block)
+    def self.spec(desc, tag: nil, fixture: nil, &block)
       node = @__node
       node.is_a?(Node)  or raise "internal error: node=#{node.inspect}"  # for debug
+      #; [!4vkbl] error when `fixture:` keyword arg is not a Hash object.
+      fixture.nil? || fixture.is_a?(Hash)  or
+        raise ArgumentError, "spec(fixture: #{fixture.inspect}): fixture argument should be a Hash object, but got #{fixture.class.name} object."
       #; [!ala78] provides raising TodoException block if block not given.
       block ||= proc { raise TodoException, "not implemented yet" }
       #; [!x48db] keeps called location only when block has parameters.
       if block.parameters.empty?
         location = nil
       else
-        location = caller(1).first  # caller() makes performance slower, but necessary.
+        location = caller_locations(1, 1).first
       end
       #; [!c8c8o] creates new spec object.
-      spec = SpecLeaf.new(node, desc, tag: tag, location: location, &block)
+      spec = SpecLeaf.new(node, desc, tag: tag, fixture: fixture, location: location, &block)
       return spec
     end
 
     def self.fixture(name, &block)
       #; [!8wfrq] registers fixture factory block.
       #; [!y3ks3] retrieves block parameter names.
-      location = caller(1).first  # caller() makes performance slower, but necessary.
+      location = caller_locations(1, 1).first
       @__node.register_fixture_block(name, location, &block)
       self
     end
@@ -730,6 +996,7 @@ module Oktest
       context = @context_class.new()
       #; [!9hbxn] context object has 'ok()' method.
       context.extend SpecHelper
+      context.extend UtilHelper
       return context
     end
 
@@ -758,7 +1025,7 @@ module Oktest
       return @hooks[key]
     end
 
-    def _repr(depth=0, buf="")
+    def _repr(depth=0, buf=String.new)
       #; [!bt5j8] builds debug string.
       if depth < 0
         id_str = "%x" % self.object_id
@@ -833,16 +1100,17 @@ module Oktest
 
   class SpecLeaf < Item
 
-    def initialize(parent, desc, tag: nil, location: nil, &block)
+    def initialize(parent, desc, tag: nil, fixture: nil, location: nil, &block)
       #@parent = parent      # not keep parent node to avoid recursive reference
       @desc  = desc
       @tag   = tag
+      @fixture  = fixture
       @location = location   # necessary when raising fixture not found error
       @block = block
       parent.add_child(self) if parent
     end
 
-    attr_reader :desc, :tag, :location, :block
+    attr_reader :desc, :tag, :fixture, :location, :block
 
     def _prefix
       '-'
@@ -863,7 +1131,7 @@ module Oktest
       nil
     end
 
-    def _repr(depth=0, buf="")       #:nodoc:
+    def _repr(depth=0, buf=String.new)       #:nodoc:
       #; [!6nsgy] builds debug string.
       buf << "  " * depth << "- #{@desc}"
       buf << " (tag: #{@tag.inspect})" if @tag
@@ -892,8 +1160,8 @@ module Oktest
 
   def self.scope(tag: nil, &block)
     #; [!kem4y] detects test script filename.
-    location = caller(1).first  # caller() makes performance slower, but necessary.
-    filename = location =~ /:\d+/ ? $` : nil
+    location = caller_locations(1, 1).first
+    filename = location.path.to_s
     #; [!6ullm] changes test script filename from absolute path to relative path.
     if filename
       pwd = Dir.pwd()
@@ -929,7 +1197,7 @@ module Oktest
       #; [!bc3l2] records invoked location.
       #; [!mqtdy] not record invoked location when `Config.ok_location == false`.
       if Config.ok_location
-        location = caller(1).first  # caller() makes performance slower, but necessary.
+        location = caller_locations(1, 1).first
       else
         location = nil
       end
@@ -944,7 +1212,7 @@ module Oktest
       #; [!agmx8] records invoked location.
       #; [!a9508] not record invoked location when `Config.ok_location == false`.
       if Config.ok_location
-        location = caller(1).first  # caller() makes performance slower, but necessary.
+        location = caller_locations(1, 1).first
       else
         location = nil
       end
@@ -970,7 +1238,7 @@ module Oktest
       #; [!wxcsp] raises error when fixture not found.
       unless tuple
         exc = FixtureNotFoundError.new("`#{name.inspect}`: fixture not found.")
-        exc.set_backtrace([caller(1).first])
+        exc.set_backtrace([caller_locations(1, 1).first.to_s])
         raise exc
       end
       #; [!m4ava] calls fixture block and returns result of it.
@@ -980,7 +1248,7 @@ module Oktest
     end
 
     def TODO()
-      location = caller(1).first   # ex: "foo_test.rb:123:in ...."
+      location = caller_locations(1, 1).first   # ex: "foo_test.rb:123:in ...."
       @__TODO = location
     end
 
@@ -1116,6 +1384,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 +1518,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 +1545,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
@@ -1246,7 +1569,8 @@ module Oktest
       begin
         params = Util.required_param_names_of_block(spec.block)
         values = params.nil? || params.empty? ? [] \
-                 : get_fixture_values(params, node, spec, context)
+                 : get_fixture_values(params, node, spec, context, spec.location,
+                                      spec.fixture ? spec.fixture.dup : {})
         spec.run_block_in_context_object(context, *values)
       rescue NoMemoryError   => exc;  raise exc
       rescue SignalException => exc;  raise exc
@@ -1271,7 +1595,7 @@ module Oktest
           exc = TODO_EXCEPTION.new("#{exc.class} raised because not implemented yet")
         end
         location = context.__TODO
-        exc.set_backtrace([location])
+        exc.set_backtrace([location.to_s])
       end
       #; [!dihkr] calls 'at_end' blocks, even when exception raised.
       begin
@@ -1285,8 +1609,8 @@ module Oktest
 
     private
 
-    def get_fixture_values(names, node, spec, context)
-      return THE_FIXTURE_MANAGER.get_fixture_values(names, node, spec, context)
+    def get_fixture_values(names, node, spec, context, location=nil, resolved=nil)
+      return THE_FIXTURE_MANAGER.get_fixture_values(names, node, spec, context, location, resolved)
     end
 
     def _call_blocks_parent_first(node, name, context)
@@ -1342,51 +1666,53 @@ module Oktest
 
   class FixtureManager
 
-    def get_fixture_values(names, node, spec, context, location=nil, _resolved={}, _resolving=[])
+    def get_fixture_values(names, node, spec, context, location, resolved={}, _resolving=[])
       #; [!w6ffs] resolves 'this_topic' fixture name as target objec of current topic.
-      _resolved[:this_topic] = node.target if !_resolved.key?(:this_topic) && node.topic?
+      resolved[:this_topic] = node.target if !resolved.key?(:this_topic) && node.topic?
       #; [!ja2ew] resolves 'this_spec' fixture name as description of current spec.
-      _resolved[:this_spec]  = spec.desc   if !_resolved.key?(:this_spec)
+      resolved[:this_spec]  = spec.desc   if !resolved.key?(:this_spec)
       #; [!v587k] resolves fixtures.
-      location ||= spec.location
       return names.collect {|name|
         #; [!np4p9] raises error when loop exists in dependency.
         ! _resolving.include?(name)  or
           raise _looped_dependency_error(name, _resolving, location)
-        get_fixture_value(name, node, spec, context, location, _resolved, _resolving)
+        get_fixture_value(name, node, spec, context, location, resolved, _resolving)
       }
     end
 
-    def get_fixture_value(name, node, spec, context, location=nil, _resolved={}, _resolving=[])
-      return _resolved[name] if _resolved.key?(name)
-      location ||= spec.location
+    def get_fixture_value(name, node, spec, context, location, resolved={}, _resolving=[])
+      return resolved[name] if resolved.key?(name)
       tuple = node.get_fixture_block(name)
       if tuple
         block, param_names, location = tuple
         #; [!2esaf] resolves fixture dependencies.
         if param_names
           _resolving << name
-          args = get_fixture_values(param_names, node, spec, context, location, _resolved, _resolving)
+          args = get_fixture_values(param_names, node, spec, context, location, resolved, _resolving)
           (popped = _resolving.pop) == name  or
             raise "** assertion failed: name=#{name.inspect}, resolvng[-1]=#{popped.inspect}"
-          #; [!4xghy] calls fixture block with context object as self.
-          val = context.instance_exec(*args, &block)
         else
-          val = context.instance_eval(&block)
+          args = []
         end
+        #; [!gyyst] overwrites keyword params by fixture values.
+        kwnames = Util.keyword_param_names_of_block(block)
+        kwargs = {}
+        kwnames.each {|name| kwargs[name] = resolved[name] if resolved.key?(name) }
+        #; [!4xghy] calls fixture block with context object as self.
+        val = context.instance_exec(*args, **kwargs, &block)
         #; [!8t3ul] caches fixture value to call fixture block only once per spec.
-        _resolved[name] = val
+        resolved[name] = val
         return val
       elsif node.parent
         #; [!4chb9] traverses parent topics if fixture not found in current topic.
-        return get_fixture_value(name, node.parent, spec, context, location, _resolved, _resolving)
+        return get_fixture_value(name, node.parent, spec, context, location, resolved, _resolving)
       elsif ! node.equal?(THE_GLOBAL_SCOPE)
         #; [!wt3qk] suports global scope.
-        return get_fixture_value(name, THE_GLOBAL_SCOPE, spec, context, location, _resolved, _resolving)
+        return get_fixture_value(name, THE_GLOBAL_SCOPE, spec, context, location, resolved, _resolving)
       else
         #; [!nr79z] raises error when fixture not found.
         exc = FixtureNotFoundError.new("#{name}: fixture not found. (spec: #{spec.desc})")
-        exc.set_backtrace([location]) if location
+        exc.set_backtrace([location.to_s]) if location
         raise exc
       end
     end
@@ -1401,7 +1727,7 @@ module Oktest
       loop = s1.empty? ? s2 : "#{s1}->#{s2}"
       #location = $1 if location =~ /(.*:\d+)/
       exc = LoopedDependencyError.new("fixture dependency is looped: #{loop}")
-      exc.set_backtrace([location])
+      exc.set_backtrace([location.to_s])
       return exc
     end
 
@@ -1429,6 +1755,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 +1766,7 @@ module Oktest
     CHARS  = { :PASS=>'.', :FAIL=>'f', :ERROR=>'E', :SKIP=>'s', :TODO=>'t' }
 
 
-    def initialize
+    def initialize()
       @exceptions = []
       @counts = {}
     end
@@ -1544,7 +1871,7 @@ module Oktest
       end
       lines = []
       msg.each_line {|line| lines << line }
-      puts lines.shift.chomp
+      puts Color.errmsg(lines.shift.chomp)
       puts lines.join.chomp unless lines.empty?
       puts exc.diff if exc.respond_to?(:diff) && exc.diff   # for oktest.rb
     end
@@ -1582,6 +1909,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)}"
@@ -1606,15 +1937,73 @@ module Oktest
         $stdout.flush
       end
       label = Color.status(status, LABELS[status] || '???')
-      msg = "#{'  ' * (depth - 1)}- [#{label}] #{spec.desc}"
+      msg = ["#{'  ' * (depth - 1)}- [#{label}] #{spec.desc}"]
       msg << " " << Color.reason("(reason: #{error.message})") if status == :SKIP
-      puts msg
+      puts msg.join()
     end
 
   end
 
 
   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,14 +2070,13 @@ module Oktest
   REPORTER_CLASSES = {
     'verbose' => VerboseReporter,  'v' => VerboseReporter,
     'simple'  => SimpleReporter,   's' => SimpleReporter,
+    'compact' => CompactReporter,  'c' => CompactReporter,
     'plain'   => PlainReporter,    'p' => PlainReporter,
     'quiet'   => QuietReporter,    'q' => QuietReporter,
   }
 
 
   def self.run(reporter: nil, style: nil)
-    #; [!kfi8b] do nothing when 'Oktest.scope()' not called.
-    return unless THE_GLOBAL_SCOPE.has_child?
     #; [!6xn3t] creates reporter object according to 'style:' keyword arg.
     klass = (style ? REPORTER_CLASSES[style] : REPORTER_CLASS)  or
       raise ArgumentError, "#{style.inspect}: unknown style."
@@ -1737,6 +2125,13 @@ module Oktest
       return param_names
     end
 
+    def keyword_param_names_of_block(block)
+      #; [!p6qqp] returns keyword param names of proc object.
+      names = []
+      block.parameters.each {|kind, name| names << name if kind == :key }
+      return names
+    end
+
     def strfold(str, width=80, mark='...')
       #; [!wb7m8] returns string as it is if string is not long.
       return str if str.bytesize <= width
@@ -1837,6 +2232,70 @@ module Oktest
       end
     end
 
+    class PartialRegexp < Regexp
+      attr_accessor :pattern_string, :begin, :end, :mark
+      def inspect()
+        #; [!uyh31] returns function call style string if @pattern_string is set.
+        if @pattern_string
+          c = @pattern_string.end_with?("\n") ? "" : ".chomp"
+          p = @pattern_string.chomp
+          b = @begin == '\A' ? "'\\A'" : @begin.inspect
+          e = @end   == '\z' ? "'\\z'" : @end.inspect
+          m = mark == "{== ==}" ? "" : ", #{mark.inspect}"
+          return "partial_regexp(<<PREXP#{c}, #{b}, #{e}#{m})\n#{p}\nPREXP\n"
+        #; [!ts9v4] returns regexp literal style string if @pattern_string is not set.
+        else
+          s = super
+          s = s.gsub(/([^\\](?:\\\\)*)((?:\\n)+)/) {
+            $1 + ("\\n\n" * ($2.length / 2))
+          }
+          if s =~ /\n/
+            s = s.sub(/\A\/(\\A)?/, "/\\1\n")
+            s = s + "x"   # `/.../x` means multiline regexp
+          end
+          return s
+        end
+      end
+    end
+
+    def partial_regexp!(pattern, begin_='\A', end_='\z', mark="{== ==}")
+      #; [!peyu4] returns PartialRegexp object which inspect string is function call styel.
+      regexp = partial_regexp(pattern, begin_, end_, mark)
+      regexp.pattern_string = pattern
+      regexp.begin = begin_; regexp.end = end_; regexp.mark = mark
+      return regexp
+    end
+
+    def partial_regexp(pattern, begin_='\A', end_='\z', mark="{== ==}")
+      mark_rexp = PARTIAL_REGEXP_CACHE[mark]
+      if mark_rexp.nil?
+        #; [!ostkw] raises error if mark has no space or has more than two spaces.
+        pair = mark.split()
+        pair.length == 2  or
+          raise ArgumentError.new("#{mark.inspect}: mark should contain only one space (ex: `{== ==}`).")
+        open  = Regexp.escape(pair[0])
+        close = Regexp.escape(pair[1])
+        mark_rexp = Regexp.compile("#{open}(.*?)#{close}")
+        PARTIAL_REGEXP_CACHE[mark] = mark_rexp
+      end
+      #; [!wn524] returns PartialRegexp object which inspect string is regexp literal style.
+      pos = 0
+      buf = []
+      buf << begin_ if begin_
+      pattern.scan(mark_rexp) do
+        m = Regexp.last_match
+        text = pattern[pos, m.begin(0) - pos]
+        buf << Regexp.escape(text) << $1.strip()
+        pos = m.end(0)
+      end
+      rest = pos == 0 ? pattern : pattern[pos..-1]
+      buf << Regexp.escape(rest) unless rest.empty?
+      buf << end_ if end_
+      return PartialRegexp.compile(buf.join())
+    end
+
+    PARTIAL_REGEXP_CACHE = {}   # :nodoc:
+
   end
 
 
@@ -1979,24 +2438,35 @@ module Oktest
     module_function
 
     def normal  s;  return s; end
-    def bold    s;  return "\e[0;1m#{s}\e[22m"; end
-    def black   s;  return "\e[1;30m#{s}\e[0m"; end
-    def red     s;  return "\e[1;31m#{s}\e[0m"; end
-    def green   s;  return "\e[1;32m#{s}\e[0m"; end
-    def yellow  s;  return "\e[1;33m#{s}\e[0m"; end
-    def blue    s;  return "\e[1;34m#{s}\e[0m"; end
-    def magenta s;  return "\e[1;35m#{s}\e[0m"; end
-    def cyan    s;  return "\e[1;36m#{s}\e[0m"; end
-    def white   s;  return "\e[1;37m#{s}\e[0m"; end
+    def bold    s;  return "\e[0;1m#{s}\e[0m"; end
+
+    def black   s;  return "\e[0;30m#{s}\e[0m"; end
+    def red     s;  return "\e[0;31m#{s}\e[0m"; end
+    def green   s;  return "\e[0;32m#{s}\e[0m"; end
+    def yellow  s;  return "\e[0;33m#{s}\e[0m"; end
+    def blue    s;  return "\e[0;34m#{s}\e[0m"; end
+    def magenta s;  return "\e[0;35m#{s}\e[0m"; end
+    def cyan    s;  return "\e[0;36m#{s}\e[0m"; end
+    def white   s;  return "\e[0;37m#{s}\e[0m"; end
+
+    def black_b   s;  return "\e[1;30m#{s}\e[0m"; end  # bold
+    def red_b     s;  return "\e[1;31m#{s}\e[0m"; end  # bold
+    def green_b   s;  return "\e[1;32m#{s}\e[0m"; end  # bold
+    def yellow_b  s;  return "\e[1;33m#{s}\e[0m"; end  # bold
+    def blue_b    s;  return "\e[1;34m#{s}\e[0m"; end  # bold
+    def magenta_b s;  return "\e[1;35m#{s}\e[0m"; end  # bold
+    def cyan_b    s;  return "\e[1;36m#{s}\e[0m"; end  # bold
+    def white_b   s;  return "\e[1;37m#{s}\e[0m"; end  # bold
 
     def topic  s; Config.color_enabled ? bold(s)   : s; end
     def spec   s; Config.color_enabled ? normal(s) : s; end
-    def pass   s; Config.color_enabled ? blue(s)   : s; end
+    def pass   s; Config.color_enabled ? cyan(s)   : s; end
     def fail   s; Config.color_enabled ? red(s)    : s; end
-    def error  s; Config.color_enabled ? red(s)    : s; end
+    def error  s; Config.color_enabled ? red_b(s)  : s; end  # bold
     def skip   s; Config.color_enabled ? yellow(s) : s; end
     def todo   s; Config.color_enabled ? yellow(s) : s; end
     def reason s; Config.color_enabled ? yellow(s) : s; end
+    def errmsg s; Config.color_enabled ? red(s)    : s; end
 
     def status(status, s)
       #; [!yev5y] returns string containing color escape sequence.
@@ -2131,6 +2601,11 @@ END
       color_enabled = nil
       opts = Options.new
       parser = option_parser(opts)
+      #; [!v5xie] parses $OKTEST_RB environment variable.
+      if ENV.key?('OKTEST_RB')
+        parser.parse(ENV['OKTEST_RB'].split())
+      end
+      #
       filenames = parser.parse(args)
       #; [!9973n] '-h' or '--help' option prints help message.
       if opts.help
@@ -2142,8 +2617,8 @@ END
         puts VERSION
         return 0
       end
-      #; [!dk8eg] '-C' or '--create' option prints test code skeleton.
-      if opts.create
+      #; [!dk8eg] '-S' or '--skeleton' option prints test code skeleton.
+      if opts.skeleton
         print SKELETON
         return 0
       end
@@ -2154,7 +2629,7 @@ END
         return 0
       end
       #; [!65vdx] prints help message if no arguments specified.
-      if filenames.empty?
+      if filenames.empty? && !THE_GLOBAL_SCOPE.has_child?
         puts help_message()
         return 0
       end
@@ -2185,7 +2660,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)
@@ -2201,7 +2677,7 @@ END
     private
 
     class Options   #:nodoc:
-      attr_accessor :help, :version, :style, :filter, :color, :create, :generate, :faster
+      attr_accessor :help, :version, :style, :filter, :color, :skeleton, :generate, :faster
     end
 
     def option_parser(opts)
@@ -2216,6 +2692,7 @@ END
       }
       parser.on('-F PATTERN') {|val|
         #; [!71h2x] '-F ...' option will be error.
+        #; [!j01y7] if filerting by '-F' matched nothing, then prints zero result.
         val =~ /\A(topic|spec|tag|sid)(=|!=)/  or
           raise OptionParser::InvalidArgument, val
         opts.filter = val
@@ -2227,7 +2704,7 @@ END
         #; [!dptgn] '--color' is same as '--color=on'.
         opts.color = val || 'on'
       }
-      parser.on('-C', '--create') { opts.create = true }
+      parser.on('-S', '--skeleton') { opts.skeleton = true }
       parser.on('-G', '--generate[=styleoption]') {|val|
         val.nil? || val == 'unaryop'  or
           raise OptionParser::InvalidArgument, val
@@ -2242,16 +2719,16 @@ END
       return HELP_MESSAGE % {command: command}
     end
 
-    HELP_MESSAGE = <<'END'
+    HELP_MESSAGE = <<'END'.gsub(/^#.*\n/, '')
 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
+  -S, --skeleton         : print test code skeleton
   -G, --generate         : generate test code skeleton from ruby file
-      --faster           : make 'ok{}' faster (for very large project)
+#      --faster           : make 'ok{}' faster (for very large project)
 
 Filter examples:
   $ oktest -F topic=Hello            # filter by topic