oktest 1.1.1 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5232c4c9a9bf78763791cf182129900a376d1dd619fbf4a21f441ea10c0a7f27
-  data.tar.gz: 1d35a5ec4678e1a80624c058a32647cc6013c6a3dc4f87f3590bea2a226ea412
+  metadata.gz: 829638b6c9703b023e61adfdef426e7ddb206f2ba93775143b8ae39c86b0f381
+  data.tar.gz: f4d70f1272398f74b0abaad9bd0ea027ca557a8860c44d6f11f056a60d89fc4c
 SHA512:
-  metadata.gz: 385ddc6a48f39657c38ee43ade9c89677aa686f8e7f55ec90eb9aef7d9dbec795cea55014e48070a22a18b63daea081863a4c6c0afc3c1d24c33316a70fcd149
-  data.tar.gz: ea3d7947b5195db3cdfd7a435adbdf0d96edfcfc0a653b67d7a241d4dec3e479c986fe8fc8294427e3c05343681b2308474131a35e5e62b75d1214660e62599e
+  metadata.gz: 5669eea2d32e6d0ecdfdd263a50e9a740fd6e2da081bbc0e35d433796d242507341bccc53c2c6ca7cd5a26d0b55a7c8222da5fb15eca27945a1207222c4ee32d
+  data.tar.gz: 8cdce5238153c774972ac26bf6b389786b920a41c8d4d2069df03d17e80ebdd299be83a63d44f7840088482b3e05e35019fdf0804a57c1273e93cde14a9a547e

data/README.md

@@ -43,7 +43,7 @@ Oktest.scope do                      #
 end                                  #
 ```
 
-Oktest.rb requires Ruby 2.3 or later.
+Oktest.rb requires Ruby 2.0 or later.
 
 
 
@@ -74,6 +74,7 @@ Oktest.rb requires Ruby 2.3 or later.
     * <a href="#at_end-crean-up-handler"><code>at_end()</code>: Crean-up Handler</a>
     * <a href="#named-fixtures">Named Fixtures</a>
     * <a href="#fixture-injection">Fixture Injection</a>
+    * <a href="#fixture-keyword-argument"><code>fixture:</code> keyword argument</a>
     * <a href="#global-scope">Global Scope</a>
   * <a href="#helpers">Helpers</a>
     * <a href="#capture_sio"><code>capture_sio()</code></a>
@@ -83,6 +84,7 @@ 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="#partial_regexp"><code>partial_regexp()</code></a>
   * <a href="#json-matcher">JSON Matcher</a>
     * <a href="#simple-example">Simple Example</a>
     * <a href="#nested-example">Nested Example</a>
@@ -91,6 +93,7 @@ Oktest.rb requires Ruby 2.3 or later.
   * <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>
+    * <a href="#environment-variale-oktest_rb">Environment Variale <code>$OKTEST_RB</code></a>
     * <a href="#traverser-class">Traverser Class</a>
     * <a href="#benchmarks">Benchmarks</a>
     * <a href="#--faster-option"><code>--faster</code> Option</a>
@@ -115,7 +118,7 @@ $ oktest --help
 $ mkdir test
 
 ### create test script
-$ oktest --create > test/example_test.rb
+$ oktest --skeleton > test/example_test.rb
 $ less test/example_test.rb
 
 ### run test script
@@ -1232,12 +1235,42 @@ end
 -->
 
 
+### `fixture:` keyword argument
+
+`scope()` takes `fixture:` keyword argument which overwrites fixture value.
+
+test/example26_test.rb:
+
+```ruby
+require 'oktest'
+
+Oktest.scope do
+
+  fixture :user do |uname, uid: 101|   # `uid` is keyword param
+    {name: uname, id: uid}
+  end
+
+  fixture :uname do
+    "Alice"
+  end
+
+  ## keyword argument `fixture:` overwrites fixture values
+  spec "example", fixture: {uname: "Bob", uid: 201} do   # !!!!!
+    |user|
+    ok {user[:name]} == "Bob"    # != "Alice"
+    ok {user[:id]}   == 201      # != 101
+  end
+
+end
+```
+
+
 ### Global Scope
 
 It is a good idea to separate common fixtures into dedicated file.
 In this case, use `Oktest.global_scope()` instead of `Oktest.scope()`.
 
-test/common_fixtures.rb:
+test/example27_test.rb:
 
 ```ruby
 require 'oktest'
@@ -1611,6 +1644,124 @@ end
 ```
 
 
+### `partial_regexp()`
+
+`partial_regexp()` can embed regexp pattern into string, and compile it into Regexp object. This is very useful to validate multiline string with regexp.
+
+Assume that you are testing the following function `f1()`. It generates multiline string containing date and random string.
+
+```ruby
+def f1()
+  today  = Date.today.to_s                  # ex: '2021-12-31'
+  secret = Random.bytes(8).unpack('H*')[0]  # ex: "cd0b260ac728eda5"
+  return <<END
+* [config.date]   #{today}
+* [config.secret] #{secret}
+END
+end
+```ruby
+
+To test `f1()`, you may write the following test code.
+As you can see, expected regexp literal is complicated.
+
+```ruby
+  topic 'f1()' do
+    spec "generates multiline string." do
+      expected = /\A\* \[config\.date\]   \d\d\d\d-\d\d-\d\d\n\* \[config\.secret\] [0-9a-f]+\n/
+      ok {f1()} =~ expected
+    end
+  end
+```
+
+[`x` option](https://ruby-doc.org/core-2.7.0/Regexp.html#class-Regexp-label-Free-Spacing+Mode+and+Comments) of regexp (such as `/.../x`) allows you to write regexp literal in multiline format.
+But you have to escape metachars (`*`, `.`, `[]`, and white space).
+
+```ruby
+  topic 'f1()' do
+    spec "generates multiline string." do
+      expected = /\A
+\*\ \[config\.date\]\ \ \ \d\d\d\d-\d\d-\d\d\n
+\*\ \[config\.secret\]\ [0-9a-f]+\n
+\z/x      # !!!!!
+      ok {f1()} =~ expected
+    end
+  end
+```
+
+In such case, `partial_regexp()` is very useful. It compiles string into Regexp object.
+Using `partial_regexp()`, you can write expected regexp very easily.
+
+```ruby
+  topic 'f1()' do
+    spec "generates multiline string." do
+      # - Regexp can be in `{== ==}`.
+      # - Other text part is escaped by `Regexp.escape()`.
+      expected = partial_regexp <<'END'      # !!!!!
+* [config.date]   {== \d\d\d\d-\d\d-\d\d ==}
+* [config.secret] {== [0-9a-f]+ ==}
+END
+      ok {f1()} =~ expected
+      ## above is equivarent to:
+      #expected = /\A
+      #\*\ \[config\.date\]\ \ \ \d\d\d\d-\d\d-\d\d\n
+      #\*\ \[config\.secret\]\ [0-9a-f]+\n
+      #\z/x      # !!!!!
+      #ok {f1()} =~ expected
+    end
+  end
+```
+
+`partial_regexp()` takes 4 arguments.
+
+```ruby
+def partial_regexp(pattern, begin_='\A', end_='\z', mark='{== ==}')
+```
+
+`partial_regexp()` adds `\A` and `\z` automatically.
+If you want not to add them, pass empty string or nil as 2nd and 3rd argument, like this:
+
+```ruby
+partial_regexp <<-'END', '', ''    # !!!!!
+...
+END
+```
+
+If you want to change embed mark, specify 4th argument, like this:
+
+```ruby
+partial_regexp <<-'END', '\A', '\z', '%%(.*?)%%'    # !!!!!
+* [config.date]   %% \d\d\d\d-\d\d-\d\d %%
+* [config.secret] %% [0-9a-f]+ %%
+END
+```
+
+Oktest.rb provides `partial_regexp!()`, too.
+Difference between `partial_regexp()` and `partial_regexp!()` is the result of `#inspect()`.
+This is imortant only when assertion failed and error message reported.
+You can use whichever you like.
+
+```ruby
+r1 = partial_regexp <<-'END'
+* [config.date]   {== \d\d\d\d-\d\d-\d\d ==}
+* [config.secret] {== [0-9a-f]+ ==}
+END
+p r1
+   #=> /\A
+   #   \*\ \[config\.date\]\ \ \ \d\d\d\d-\d\d-\d\d\n
+   #   \*\ \[config\.secret\]\ [0-9a-f]+\n
+   #   \z/x
+
+r2 = partial_regexp! <<-'END'                   # !!!!!
+* [config.date]   {== \d\d\d\d-\d\d-\d\d ==}
+* [config.secret] {== [0-9a-f]+ ==}
+END
+p r2
+   #=> partial_regexp(<<PREXP, '\A', '\z')
+   #   * [config.date]   {== \d\d\d\d-\d\d-\d\d ==}
+   #   * [config.secret] {== [0-9a-f]+ ==}
+   #   PREXP
+```
+
 
 ## JSON Matcher
 
@@ -1922,6 +2073,20 @@ end
 ```
 
 
+### Environment Variale `$OKTEST_RB`
+
+You can set default command-line option to environment variale `$OKTEST_RB`.
+For examle, you can specify default reporting style with `$OKTEST_RB`.
+
+```terminal
+### change default reporting style to plain-style.
+$ export OKTEST_RB="-s plain"                  # !!!!!
+
+### run test script in plain-style reporting without '-s' option.
+$ ruby test/foo_test.rb
+```
+
+
 ### Traverser Class
 
 Oktest.rb provides `Traverser` class which implements Visitor pattern.
@@ -2001,12 +2166,12 @@ Oktest.rb gem file contains benchmark script.
 It shows that Oktest.rb runs more than three times faster than RSpec.
 
 ```terminal
-$ gem install oktest        # ver 1.0.0
+$ gem install oktest        # ver 1.2.0
 $ gem install rspec         # ver 3.10.0
 $ gem install minitest      # ver 5.14.4
 $ gem install test-unit     # ver 3.4.4
 
-$ cp -pr $GEM_HOME/gems/oktest-1.0.0/benchmark .
+$ cp -pr $GEM_HOME/gems/oktest-1.2.0/benchmark .
 $ cd benchmark/
 $ rake -T
 $ ruby --version
@@ -2018,47 +2183,57 @@ $ rake benchmark:all
 Example result:
 
 ```
-==================== oktest ====================
+==================== {{*oktest*}} ====================
 oktest -sq run_all.rb
 
-## total:100000 (pass:100000, fail:0, error:0, skip:0, todo:0) in 4.86s
+## total:100000 (pass:100000, fail:0, error:0, skip:0, todo:0) in 2.36s
 
-        8.536 real        8.154 user        0.245 sys
+        {{*6.815 real*}}        6.511 user        0.257 sys
 
-==================== oktest:faster ====================
+==================== {{*oktest:faster*}} ====================
 oktest -sq --faster run_all.rb
 
-## total:100000 (pass:100000, fail:0, error:0, skip:0, todo:0) in 1.64s
+## total:100000 (pass:100000, fail:0, error:0, skip:0, todo:0) in 2.01s
 
-        5.068 real        4.819 user        0.202 sys
+        {{*6.401 real*}}        6.123 user        0.240 sys
 
-==================== rspec ====================
+==================== {{*rspec*}} ====================
 rspec run_all.rb | tail -4
 
-Finished in 14.44 seconds (files took 15.81 seconds to load)
+Finished in 15.27 seconds (files took 16.08 seconds to load)
 100000 examples, 0 failures
 
 
-        30.798 real        26.565 user        4.392 sys
+        {{*32.062 real*}}        27.778 user        4.383 sys
 
-==================== minitest ====================
+==================== {{*minitest*}} ====================
 ruby run_all.rb | tail -4
 
-Finished in 5.190405s, 19266.3193 runs/s, 19266.3193 assertions/s.
+Finished in 5.281425s, 18934.2838 runs/s, 37868.5677 assertions/s.
 
-100000 runs, 100000 assertions, 0 failures, 0 errors, 0 skips
+100000 runs, 200000 assertions, 0 failures, 0 errors, 0 skips
 
-        8.767 real        8.157 user        0.761 sys
+        {{*9.140 real*}}        8.657 user        0.705 sys
 
-==================== testunit ====================
+==================== {{*testunit*}} ====================
 ruby run_all.rb | tail -5
 -------------------------------------------------------------------------------
-100000 tests, 100000 assertions, 0 failures, 0 errors, 0 pendings, 0 omissions, 0 notifications
+100000 tests, 200000 assertions, 0 failures, 0 errors, 0 pendings, 0 omissions, 0 notifications
 100% passed
 -------------------------------------------------------------------------------
-8957.19 tests/s, 8957.19 assertions/s
+7775.59 tests/s, 15551.18 assertions/s
 
-        17.838 real        17.201 user        0.879 sys
+        {{*19.580 real*}}        19.020 user        0.885 sys
+```
+
+Summary:
+
+```
+Oktest:              6.815 real     6.511 user     0.257 sys
+Oktest (--fast):     6.401 real     6.123 user     0.240 sys
+RSpec:              32.062 real    27.778 user     4.383 sys
+MiniTest:            9.140 real     8.657 user     0.705 sys
+Test::Unit:         19.580 real    19.020 user     0.885 sys
 ```
 
 

data/Rakefile.rb

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 
 ###
-### $Release: 1.1.1 $
+### $Release: 1.2.0 $
 ### $Copyright: copyright(c) 2011-2021 kuwata-lab.com all rights reserved $
 ### $License: MIT License $
 ###
@@ -37,6 +37,8 @@ How to release:
   $ git add -p CHANGES.md
   $ git commit -m "ruby: update 'CHANGES.md'"
   $ git log -1
+  $ cid=$(git log -1 | awk 'NR==1{print $2}')
+  $ echo $cid
   $ rake package RELEASE=#{rel}
   $ rake package:extract            # confirm files in gem file
   $ pushd #{proj}-#{rel}/data; find . -type f; popd
@@ -48,7 +50,8 @@ How to release:
   $ git push --tags
   $ rake clean
   $ git checkout ruby
-  $ git cherry-pick xxxxxxxxx       # cherry-pick update of CHANGES.md
+  $ git log -1 $cid
+  $ git cherry-pick $cid            # cherry-pick update of CHANGES.md
 END
 end
 

data/benchmark/Rakefile.rb

@@ -29,6 +29,7 @@ Oktest.scope do
 <%     for k in 1..nspecs %>
       spec "#<%= k %>: 1+1 should be 2" do
         ok {1+1} == 2
+        ok {1+1} == 2
       end
 <%     end %>
 
@@ -54,6 +55,7 @@ RSpec.describe "Example #<%= i %>" do
 <%     for k in 1..nspecs %>
     it "#<%= k %>: 1+1 should be 2" do
       expect(1+1).to eq 2
+      expect(1+1).to eq 2
     end
 <%     end %>
 
@@ -80,6 +82,7 @@ describe "Example #<%= i %>" do
 <%     for k in 1..nspecs %>
     it "#<%= k %>: 1+1 should be 2" do
       assert_equal 2, 1+1
+      assert_equal 2, 1+1
     end
 <%     end %>
 
@@ -107,6 +110,7 @@ class Example_<%= n %>_<%= i %>_TC < Test::Unit::TestCase
     def test_<%= n %>_<%= i %>_<%= j %>_<%= k %>()
       #assert 1+1 == 2
       assert_equal 2, 1+1
+      assert_equal 2, 1+1
     end
 <%     end %>