oktest 1.3.1 → 1.5.0

data/lib/oktest.rb

@@ -1,7 +1,8 @@
 # -*- coding: utf-8 -*-
+# frozen_string_literal: true
 
 ###
-### $Release: 1.3.1 $
+### $Release: 1.5.0 $
 ### $Copyright: copyright(c) 2011-2024 kuwata-lab.com all rights reserved $
 ### $License: MIT License $
 ###
@@ -12,7 +13,7 @@ require 'set'
 module Oktest
 
 
-  VERSION = '$Release: 1.3.1 $'.split()[1]
+  VERSION = '$Release: 1.5.0 $'.split()[1]
 
 
   class OktestError < StandardError
@@ -380,6 +381,18 @@ module Oktest
       return exc
     end
 
+    def raise_nothing?()
+      __done()
+      #; [!leqey] do nothing without calling proc object.
+      proc_obj = @actual
+      if @bool
+        proc_obj.call
+      #; [!a61b7] not available with `.NOT`.
+      else
+        raise OktestError, "`raise_nothing?()` is not available with `.NOT`."
+      end
+    end
+
     def throw?(expected)
       __done()
       proc_obj = @actual
@@ -858,17 +871,23 @@ END
     end
 
     def self.case_when(desc, tag: nil, &block)
-      #; [!g3cvh] returns topic object.
       #; [!ofw1i] target is a description starting with 'When '.
-      return __case_when("When #{desc}", tag, &block)
+      #; [!53qxv] not add 'When ' if description starts with it.
+      rexp = /^(\[!\w+\] )?[wW]hen\b/
+      desc2 = desc =~ rexp ? desc : "When #{desc}"
+      #; [!g3cvh] returns topic object.
+      return __case_when(desc2, tag, &block)
     end
 
     def self.case_else(desc=nil, tag: nil, &block)
       #; [!hs1to] 1st parameter is optional.
-      desc = desc ? "Else #{desc}" : "Else"
-      #; [!oww4b] returns topic object.
+      desc ||= "Else"
       #; [!j5gnp] target is a description which is 'Else'.
-      return __case_when(desc, tag, &block)
+      #; [!3nn8d] not add 'Else ' if description starts with it.
+      rexp = /^(\[!\w+\] )?[eE]lse\b/
+      desc2 = desc =~ rexp ? desc : "Else #{desc}"
+      #; [!oww4b] returns topic object.
+      return __case_when(desc2, tag, &block)
     end
 
     def self.__case_when(desc, tag, &block)  #:nodoc:
@@ -1106,6 +1125,13 @@ END
     attr_reader :target
     attr_writer :_prefix
 
+    def run_block_in_context_class(&block)
+      #; [!i2kvj] run block in context class.
+      #; [!pr3vj] run block with topic target as an argument.
+      target = @target
+      @context_class.class_exec(target, &block)
+    end
+
     def _prefix
       @_prefix || '*'
     end
@@ -1215,6 +1241,13 @@ END
     @_in_scope = false
   end
 
+  def self.topic(target, &block)
+    #; [!c5j3f] same as `Oktest.scope do topic target do ... end end`.
+    self.scope do
+      topic(target, &block)
+    end
+  end
+
 
   module SpecHelper
 
@@ -1284,7 +1317,7 @@ END
       (@__at_end_blocks ||= []) << block
     end
 
-    def capture_sio(input="", tty: false, &b)
+    def capture_stdio(input="", tty: false, &b)
       require 'stringio' unless defined?(StringIO)
       bkup = [$stdin, $stdout, $stderr]
       #; [!53mai] takes $stdin data.
@@ -1306,6 +1339,58 @@ END
       $stdin, $stdout, $stderr = bkup
     end
 
+    #; [!qjmaa] 'capture_sio()' is an alias of 'capture_stdio()'.
+    alias capture_sio capture_stdio
+
+    def capture_stdout(input="", tty: false, &b)
+      #; [!4agii] same as `sout, serr = capture_stdio(); ok {serr} == ''`.
+      #; [!may84] fails when stderr is not empty.
+      sout, serr = capture_stdio(input, tty: tty, &b)
+      serr == ""  or
+        raise FAIL_EXCEPTION, "Output of $stderr expected to be empty, but got: #{serr.inspect}"
+      #; [!5n04e] returns output of stdout.
+      return sout
+    end
+
+    def capture_stderr(input="", tty: false, &b)
+      #; [!46tj4] same as `sout, serr = capture_stdio(); ok {sout} == ''`.
+      #; [!3zh32] fails when stdout is not empty.
+      sout, serr = capture_stdio(input, tty: tty, &b)
+      sout == ""  or
+        raise FAIL_EXCEPTION, "Output of $stdout expected to be empty, but got: #{sout.inspect}"
+      #; [!5vs64] returns output of stderr.
+      return serr
+    end
+
+    def capture_command(command, input="", &error_handler)
+      require 'open3' unless defined?(::Open3)
+      #; [!wyp17] executes command with stdin data.
+      sout, serr, pstat = ::Open3.capture3(command, :stdin_data=>input)
+      #; [!jd63p] raises error if command failed.
+      #; [!lsmgq] calls error handler block if command failed.
+      #; [!vivq3] doesn't call error handler block if command finished successfully.
+      #; [!nxw59] not raise error if command failed and error handler specified.
+      if pstat.exitstatus != 0
+        if block_given?()
+          yield pstat
+        else
+          raise "Command failed with status (#{pstat.exitstatus}): `#{command}`"
+        end
+      end
+      #; [!h5994] returns output of stdin and stderr.
+      return sout, serr
+    end
+
+    def capture_command!(command, input="", &error_handler)
+      #; [!vlbpo] executes command with stdin data.
+      #; [!yfohb] not raise error even if command failed.
+      #; [!andyj] calls error handler block if command failed.
+      #; [!xnkqc] doesn't call error handler block if command finished successfully.
+      #; [!3xdgo] returns output of stdin and stderr.
+      error_handler ||= proc do end
+      capture_command(command, input, &error_handler)
+    end
+
     def __do_dummy(val, recover, &b)
       if block_given?()
         begin
@@ -2097,9 +2182,6 @@ END
   end
 
 
-  REPORTER_CLASS = VerboseReporter
-
-
   REPORTER_CLASSES = {
     'verbose' => VerboseReporter,  'v' => VerboseReporter,
     'simple'  => SimpleReporter,   's' => SimpleReporter,
@@ -2108,10 +2190,22 @@ END
     'quiet'   => QuietReporter,    'q' => QuietReporter,
   }
 
+  DEFAULT_REPORTING_STYLE = 'verbose'
+
+  def self.DEFAULT_REPORTING_STYLE=(style)
+    #; [!lbufd] raises error if unknown style specified.
+    REPORTER_CLASSES.key?(style)  or
+      raise ArgumentError, "#{style}: Unknown reporting style."
+    #; [!dsbmo] changes value of default reporting style.
+    remove_const :DEFAULT_REPORTING_STYLE
+    const_set    :DEFAULT_REPORTING_STYLE, style
+  end
+
 
   def self.run(reporter: nil, style: nil)
     #; [!6xn3t] creates reporter object according to 'style:' keyword arg.
-    klass = (style ? REPORTER_CLASSES[style] : REPORTER_CLASS)  or
+    style ||= DEFAULT_REPORTING_STYLE
+    klass = REPORTER_CLASSES[style]  or
       raise ArgumentError, "#{style.inspect}: unknown style."
     reporter ||= klass.new
     #; [!mn451] run test cases.
@@ -2419,12 +2513,12 @@ END
     public
 
     def filter_children!(node)
-      _filter_children!(node)
+      _filter_children!(node, 0)
     end
 
     private
 
-    def _filter_children!(node)   #:nodoc:
+    def _filter_children!(node, _depth)   #:nodoc:
       #; [!r6g6a] supports negative filter by topic.
       #; [!doozg] supports negative filter by spec.
       #; [!ntv44] supports negative filter by tag name.
@@ -2445,7 +2539,7 @@ END
           removes << i unless positive
         #; [!mz6id] can filter nested topics.
         elsif item.is_a?(Node)
-          removes << i unless _filter_children!(item)
+          removes << i unless _filter_children!(item, _depth+1)
         #; [!1jphf] can filter specs from nested topics.
         elsif item.is_a?(SpecLeaf)
           removes << i if positive
@@ -2580,7 +2674,8 @@ END
           _transform(child_tuple, depth+1, buf)
         end
         buf << "\n"
-        buf << "#{indent}  end  # #{topic}\n"
+        buf << "#{indent}  end\n"                  if keyword == 'def'
+        buf << "#{indent}  end  # #{topic}\n"  unless keyword == 'def'
         buf << "\n"
       end
     end
@@ -2607,6 +2702,11 @@ END
 
   class MainApp
 
+    def initialize(command=nil)
+      @command = command || File.basename($0)
+      @schema  = option_schema()
+    end
+
     def self.main(argv=nil)
       #; [!tb6sx] returns 0 when no errors raised.
       #; [!d5mql] returns 1 when a certain error raised.
@@ -2617,48 +2717,40 @@ END
       #; [!jr49p] reports error when unknown option specified.
       #; [!uqomj] reports error when required argument is missing.
       #; [!8i755] reports error when argument is invalid.
-      rescue OptionParser::ParseError => exc
-        case exc
-        when OptionParser::InvalidOption   ; s = "unknown option."
-        when OptionParser::InvalidArgument ; s = "invalid argument."
-        when OptionParser::MissingArgument ; s = "argument required."
-        else                               ; s = nil
-        end
-        msg = s ? "#{exc.args.join(' ')}: #{s}" : exc.message
-        $stderr.puts("#{File.basename($0)}: #{msg}")
+      rescue Benry::CmdOpt::OptionError => exc
+        $stderr.puts("[ERROR] #{exc.message}")
         return 1
       end
     end
 
     def run(*args)
       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())
+        args = ENV['OKTEST_RB'].split() + args
       end
-      #
-      filenames = parser.parse(args)
+      #; [!tt2gj] parses command options even after filenames.
+      opts = parse_opts(args)
+      filenames = args
       #; [!9973n] '-h' or '--help' option prints help message.
-      if opts.help
+      if opts[:help]
         puts help_message()
         return 0
       end
       #; [!qqizl] '--version' option prints version number.
-      if opts.version
+      if opts[:version]
         puts VERSION
         return 0
       end
       #; [!dk8eg] '-S' or '--skeleton' option prints test code skeleton.
-      if opts.skeleton
-        print SKELETON
+      if opts[:skeleton]
+        print skeleton()
         return 0
       end
       #; [!uxh5e] '-G' or '--generate' option prints test code.
       #; [!wmxu5] '--generate=unaryop' option prints test code with unary op.
-      if opts.generate
-        print generate(filenames, opts.generate)
+      if opts[:generate]
+        print generate(filenames, opts[:generate])
         return 0
       end
       #; [!65vdx] prints help message if no arguments specified.
@@ -2668,12 +2760,12 @@ END
       end
       #; [!6ro7j] '--color=on' option enables output coloring forcedly.
       #; [!vmw0q] '--color=off' option disables output coloring forcedly.
-      if opts.color
+      if opts[:color] != nil
         color_enabled = Config.color_enabled
-        Config.color_enabled = (opts.color == 'on')
+        Config.color_enabled = opts[:color]
       end
       #; [!qs8ab] '--faster' chanages 'Config.ok_location' to false.
-      if opts.faster
+      if opts[:faster]
         Config.ok_location = false    # will make 'ok{}' faster
       end
       #
@@ -2685,8 +2777,8 @@ END
       #; [!8uvib] '-F tag=...' option filters by tag name.
       #; [!m0iwm] '-F sid=...' option filters by spec id.
       #; [!noi8i] '-F' option supports negative filter.
-      if opts.filter
-        filter_obj = FILTER_CLASS.create_from(opts.filter)
+      if opts[:filter]
+        filter_obj = FILTER_CLASS.create_from(opts[:filter])
         Oktest.filter(filter_obj)
       end
       #; [!bim36] changes auto-running to off.
@@ -2697,7 +2789,7 @@ END
       #; [!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)
+      n_errors = Oktest.run(:style=>opts[:style])
       #; [!dsrae] reports if 'ok()' called but assertion not performed.
       AssertionObject.report_not_yet()
       #; [!bzgiw] returns total number of failures and errors.
@@ -2709,74 +2801,70 @@ END
 
     private
 
-    class Options   #:nodoc:
-      attr_accessor :help, :version, :style, :filter, :color, :skeleton, :generate, :faster
-    end
+    def option_schema()
+      require 'benry/cmdopt' unless defined?(::Benry::CmdOpt)
+      reporting_styles = REPORTER_CLASSES.keys.partition {|s| s.length > 1 }.flatten()
+      schema = Benry::CmdOpt::Schema.new()
+      schema.add(:help    , "-h, --help"   , "show help")
+      schema.add(:version , "    --version", "print version")
+      schema.add(:style   , "-s <reporting-style>", "verbose/simple/compact/plain/quiet, or v/s/c/p/q",
+                                             enum: reporting_styles)
+      #; [!71h2x] '-F ...' option will be error.
+      #; [!j01y7] if filerting by '-F' matched nothing, then prints zero result.
+      schema.add(:filter  , "-F <key>=<pattern>", "filter topic or spec with pattern (see below)",
+                                             rexp: /\A(topic|spec|tag|sid)(=|!=)/)
+      #; [!dptgn] '--color' is same as '--color=on'.
+      schema.add(:color   , "    --color[=<on|off>]", "enable/disable output coloring forcedly",
+                                             type: TrueClass)
+      schema.add(:skeleton, "-S, --skeleton", "print test code skeleton")
+      schema.add(:generate, "-G, --generate[=<style>]", "generate test code skeleton from ruby file",
+                                             enum: ['unaryop'])
+      schema.add(:faster  , "    --faster" , "make 'ok{}' faster (for very large project)",
+                                             hidden: true)
+      return schema
+    end
+
+    def parse_opts(args)
+      parser = Benry::CmdOpt::Parser.new(@schema)
+      return parser.parse(args, all: true)
+    end
+
+    def help_message()
+      command = @command
+      schema  = @schema
+      #; [!v938d] help message will be colored only when stdout is a tty.
+      if $stdout.tty?
+        bold   = proc {|s| "\e[1m#{s}\e[0m" }    # bold
+        header = proc {|s| "\e[36m#{s}\e[0m" }   # cyan
+      else
+        bold = header = proc {|s| s }
+      end
+      return <<"END"
+#{bold.('Oktest')} (#{VERSION}) -- New style testing library
 
-    def option_parser(opts)
-      require 'optparse' unless defined?(OptionParser)
-      parser = OptionParser.new
-      parser.on('-h', '--help')    { opts.help    = true }
-      parser.on(      '--version') { opts.version = true }
-      parser.on('-s STYLE') {|val|
-        REPORTER_CLASSES.key?(val)  or
-          raise OptionParser::InvalidArgument, val
-        opts.style = val
-      }
-      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
-      }
-      parser.on(      '--color[={on|off}]') {|val|
-        #; [!9nr94] '--color=true' option raises error.
-        val.nil? || val == 'on' || val == 'off'  or
-          raise OptionParser::InvalidArgument, val
-        #; [!dptgn] '--color' is same as '--color=on'.
-        opts.color = val || 'on'
-      }
-      parser.on('-S', '--skeleton') { opts.skeleton = true }
-      parser.on('-G', '--generate[=styleoption]') {|val|
-        val.nil? || val == 'unaryop'  or
-          raise OptionParser::InvalidArgument, val
-        opts.generate = val || true
-      }
-      parser.on(      '--faster') { opts.faster = true }
-      return parser
-    end
-
-    def help_message(command=nil)
-      command ||= File.basename($0)
-      return HELP_MESSAGE % {command: command}
-    end
-
-    HELP_MESSAGE = <<'END'.gsub(/^#.*\n/, '')
-Usage: %{command} [<options>] [<file-or-directory>...]
-  -h, --help             : show help
-      --version          : print version
-  -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
-  -S, --skeleton         : print test code skeleton
-  -G, --generate         : generate test code skeleton from ruby file
-#      --faster           : make 'ok{}' faster (for very large project)
-
-Filter examples:
-  $ oktest -F topic=Hello            # filter by topic
-  $ oktest -F spec='*hello*'         # filter by spec
-  $ oktest -F tag=name               # filter by tag name
-  $ oktest -F tag!=name              # negative filter by tag name
-  $ oktest -F tag='{name1,name2}'    # filter by multiple tag names
-
-See https://github.com/kwatch/oktest/blob/ruby/ruby/README.md for details.
+#{header.('Usage:')}
+  $ #{bold.(command)} [<options>] [<file|directory>...]
+
+#{header.('Options:')}
+#{schema.to_s.chomp}
+
+#{header.('Filter Examples:')}
+  $ #{command} -F topic=Hello            # filter by topic
+  $ #{command} -F spec='*hello*'         # filter by spec
+  $ #{command} -F tag=name               # filter by tag name
+  $ #{command} -F tag!=name              # negative filter by tag name
+  $ #{command} -F tag='{name1,name2}'    # filter by multiple tag names
+
+#{header.('Document:')}
+  https://github.com/kwatch/oktest/blob/ruby/ruby/README.md
 END
+    end
 
     def load_files(filenames)
       filenames.each do |fname|
+        #; [!k402d] raises error if file not found.
         File.exist?(fname)  or
-          raise OptionParser::InvalidOption, "#{fname}: not found."
+          raise Benry::CmdOpt::OptionError, "#{fname}: not found."
       end
       filenames.each do |fname|
         File.directory?(fname) ? load_dir(fname) : load(fname)
@@ -2801,49 +2889,15 @@ END
       return buf.join()
     end
 
-    SKELETON = <<'END'
-# coding: utf-8
-
-## see https://github.com/kwatch/oktest/blob/ruby/ruby/README.md for details.
-require 'oktest'
-
-Oktest.scope do
-
-  fixture :alice do
-    {name: "Alice"}
-  end
-  fixture :bob do
-    {name: "Bob"}
-  end
-
-  topic Class do
-
-    before do nil end
-    after do nil end
-    before_all do nil end
-    after_all do nil end
-
-    topic '#method_name()' do
-
-      spec "1+1 should be 2." do
-        ok {1+1} == 2
-      end
-
-      spec "fixture injection examle." do
-        |alice, bob|
-        ok {alice[:name]} == "Alice"
-        ok {bob[:name]} == "Bob"
-      end
-
+    def skeleton()
+      #; [!s2i1p] returns skeleton string of test script.
+      #; [!opvik] skeleton string is valid ruby code.
+      str = File.read(__FILE__, encoding: 'utf-8')
+      return str.split(/^__END__\n/, 2)[1]
     end
 
   end
 
-end
-END
-
-  end
-
 
   def self.main(argv=nil)
     status = MainApp.main(argv)
@@ -2876,3 +2930,59 @@ if __FILE__ == $0
   $LOADED_FEATURES << File.expand_path(__FILE__)  # avoid loading oktest.rb twice
   Oktest.main()   # run test scripts
 end
+
+
+__END__
+# coding: utf-8
+
+## see https://github.com/kwatch/oktest/blob/ruby/ruby/README.md for details.
+require 'oktest'
+
+
+## define common fixtures or helper methods in global scope block.
+## (strongly recommended to separate global scope block into a dedicated file.)
+Oktest.global_scope do
+
+  fixture :alice do           # global fixture example
+    {name: "Alice"}
+  end
+
+end
+
+
+## define test cases and fixtures in normal scope block.
+Oktest.scope do
+
+  fixture :bob do             # local fixture example
+    {name: "Bob"}
+  end
+
+  topic Class do
+
+    before do nil end
+    after do nil end
+    before_all do nil end
+    after_all do nil end
+
+    topic '#method_name()' do
+
+      spec "1+1 should be 2." do
+        ok {1+1} == 2
+      end
+
+      spec "1/0 should raise error." do
+        pr = proc { 1/0 }
+        ok {pr}.raise?(ZeroDivisionError, /divided by 0/)
+      end
+
+      spec "fixture injection examle." do
+        |alice, bob|
+        ok {alice[:name]} == "Alice"
+        ok {bob[:name]} == "Bob"
+      end
+
+    end
+
+  end
+
+end

data/oktest.gemspec

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 
 ###
-### $Release: 1.3.1 $
+### $Release: 1.5.0 $
 ### $License: MIT License $
 ### $Copyright: copyright(c) 2011-2024 kuwata-lab.com all rights reserved $
 ###
@@ -13,7 +13,7 @@ Gem::Specification.new do |s|
   s.name        = "oktest"
   s.author      = "kwatch"
   s.email       = "kwatch@gmail.com"
-  s.version     = "$Release: 1.3.1 $".split()[1]
+  s.version     = "$Release: 1.5.0 $".split()[1]
   s.license     = "MIT"
   s.platform    = Gem::Platform::RUBY
   s.homepage    = "https://github.com/kwatch/oktest/tree/ruby/ruby"
@@ -31,6 +31,7 @@ See https://github.com/kwatch/oktest/tree/ruby/ruby for details.
 END
   s.required_ruby_version = ">= 2.4"
   s.add_dependency "diff-lcs", "~> 1.0"
+  s.add_dependency "benry-cmdopt", "~> 2.3"
   s.add_dependency "benry-recorder", "~> 1.0"
 
   ## files
@@ -40,5 +41,5 @@ END
   s.files       = files
   s.executables = ['oktest']
   s.bindir      = 'bin'
-  s.test_file   = 'test/run_all.rb'
+  s.test_file   = 'test/all.rb'
 end

data/test/{run_all.rb → all.rb}

@@ -1,4 +1,5 @@
 # -*- coding: utf-8 -*-
+# frozen_string_literal: true
 
 #Dir.chdir File.dirname(__FILE__) do
 #  Dir.glob("**/*_test.rb") do |x|