uspec 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b9c8a47af991d099f6804066c5ef9e2d8ac0c4cca8023a919354bc247ee3d901
-  data.tar.gz: 14e4c49e40bf1a2cf19553b41c27107c7d13f110978dad55d951242a2e86fcc6
+  metadata.gz: d17e77cb5065265172f613c90f9edfb022c217386b56d34af6858b078ba406d8
+  data.tar.gz: 1c77be04e49ca61e243d7c35aa84c9de56dac3ae8f099ba351f6efa5d9a5ca38
 SHA512:
-  metadata.gz: b1781f78237157872c0ad40f5c009a4dbed94b78049973feb164f49ea3c042dbcc022ec80d423ee5d69a0d0ca3f0d48dfe4e81a227848500a3af1466c15e015e
-  data.tar.gz: 3ecaada229d7bc0ee4a0c3d473654c5544863c11dd390cde47e8e08d25205a5bfe8175de8b96a1a4f93aa9b499b119d702bc8f4723a1aa371b5b134e1af7d371
+  metadata.gz: cf99ec58c05e076e9060b7ac71271e5fcdfd8ab44e03810b41a1ac2a67a4921777dca4ed2a5c27637f071b20fabb0262118b4a7214448b63ea8193450dc663b6
+  data.tar.gz: eb1c4de66aef1dfef542774fd18b9484bf26778bfe5651c0594fc6cd543472003c32484048435a41d9baacdf3695376fcb1e25fd659ff36183072ddb44eafb41

data/README.markdown

@@ -12,26 +12,20 @@ Philosophy / Why Uspec?
 
 > Uspec is just Ruby!
 
-Unlike other testing frameworks there's no need for special matchers,
-there can only be one assertion per test,
-and you never have to worry that your tests lack assertions.
+- There's no need for special matchers
+- You never have to worry that your tests lack assertions
+- There is no monkey patching of core classes
 
-That's because when the `spec` block is evaluated the return value is used (in a very ruby-like way)
-to determine if the test has passed or failed. Standard Ruby comparisons are your friend!
-No more digging around in your test framework's documentation to figure out what matcher you're supposed to use.
-This also means *no monkey patching* core classes!
+No more digging around in your test framework's documentation to figure out what matcher you're supposed to use. Because you just use Ruby!
 
-Uspec's output is in beautiful ansi technicolor,
-with red for failures, green for successes, and yellow for pending specs. Here's a screenshot:
-
-![Screenshot!](https://i.imgur.com/Baqggck.png)
+Uspec is well under 500 lines of code. Most of that is there to gracefully handle the weird edge cases that pop up all the time during development and testing of software. Uspec will catch issues at every stage and display a nicely formatted message to provide hints at what might have gone wrong.
 
 Uspec is tiny, painless, and easy to use. Download it and give it a try!
 
-Example
--------
+Writing Tests
+----------
 
-Uspec is **just Ruby**. The DSL is minimal - there's only one method to remember!
+Uspec is deceptively simple. You only need to remember one method: `spec`. 
 
 Writing a spec is easy:
 
@@ -43,31 +37,18 @@ end
 
 That's it!
 
-Installation
-------------
-
-Add this line to your application's Gemfile:
-
-    gem 'uspec'
-
-And then execute:
-
-    $ bundle
-
-Or install it directly with:
-
-    $ gem install uspec
-
-
 Quickstart
 ----------
 
-0. Create a `uspec` directory to keep your specs in.
-1. Name your specs ending with `_spec.rb`.
-2. Write some specs in Ruby using the `spec` method (example above).
-2. Use the included `uspec` executable to run your specs.
+1. Install in the typical way using Rubygems or Bundler:
+    - `gem install uspec`
+    - `echo 'gem "uspec"' >> Gemfile && bundle install`
+2. Create a `uspec` directory to keep your specs in
+3. Name your specs ending with `_spec.rb`
+4. Write some specs in Ruby using the `spec` method (example above)
+5. Use the included `uspec` executable to run your specs
 
-**Hint:** A lot of people also put `require_relative 'spec_helper'` at the top of their test files for sharing code between tests.
+And always remember that Uspec is **just Ruby**!
 
 Commandline Usage
 -----------------
@@ -78,19 +59,23 @@ uspec - minimalistic ruby testing framework
 usage: uspec [<file_or_path>...]
 ```
 
-- Without arguments the `uspec` command will automatially look for a `uspec` directory and load any `*_spec.rb` files inside them.
+- Without arguments the `uspec` command will automatically look for a `uspec` directory and load any `*_spec.rb` files inside it.
 - You can also pass in arbitrary files and it will attempt to run them as specs.
 - If you pass in directories `uspec` will scan for and run any specs inside them.
-- Uspec will return the number of failures as its status code to the commandline, 0 if none.
+- Uspec will return the number of failures as its exit status code to the or `0` if none.
 
 Output
 ------
 
+Uspec's output is in beautiful ANSI technicolor, with red for failures, green for successes, and yellow for pending specs.
+
+![Screenshot!](https://i.imgur.com/Baqggck.png)
+
 A brief explanation of `uspec`'s output to show you what it can do!
 
 ### Success
 
-If a spec passes (returns true):
+If a spec passes (returns `true`):
 
 ```
  -- AwesomeMcCoolname.generate creates a cool name: true
@@ -98,7 +83,7 @@ If a spec passes (returns true):
 
 ### Failure
 
-If a spec fails (returns false):
+If a spec fails (returns `false`):
 
 ```
  -- AwesomeMcCoolname.generate creates a cool name: false
@@ -106,7 +91,7 @@ If a spec fails (returns false):
 
 ### Exception
 
-If the spec encounters an error (raises an Exception):
+If the spec encounters an error (raises an `Exception`):
 
 ```
  -- AwesomeMcCoolname.generate creates a cool name: Exception
@@ -132,7 +117,7 @@ end
 
 Then Uspec will let you know so you can debug it:
 
-```ruby
+```
  -- AwesomeMcCoolname.generate creates a badass name: Failed
 
     Spec did not return a boolean value
@@ -155,8 +140,59 @@ When you run the test Uspec will helpfully display:
  -- a feature I have not implemented yet: pending
 ```
 
-Tips & Tricks
--------------
+Reusing Test Code
+------------
+
+Test code reuse doesn't require doing anything special. It's just like any other Ruby code. But here are a few examples!
+
+**Hint:** A lot of people put `require_relative 'spec_helper'` at the top of their test files and put shared code and helper methods in a file called `spec_helper.rb`.
+
+### Methods
+
+If you find yourself repeating the same code in tests several times you can extract that code into a method and then call it within your `spec` blocks.
+
+```ruby
+def new_generator
+  AwesomeMcCoolname.new max_length: 15
+end
+
+spec 'generates a cool name' do
+  new_generator.generate.include? 'Badass'
+end
+```
+
+### Instance Variables
+
+This also works for instance variables!
+
+```ruby
+@favorite_color = 'fuschia'
+
+spec 'remembers favorite color' do
+  ColorDB.fetch(:favorite) == @favorite_color
+end
+```
+
+### Memoized Methods
+
+By combining the previous two capabilities of Ruby, it is trivial to memoize method output as well:
+
+```ruby
+def reusable_generator
+  @reusable_generator ||= AwesomeMcCoolname.new max_length: 15
+end
+
+spec 'generates a cool name' do
+  reusable_generator.generate.include? 'Badass'
+end
+```
+
+This is all the same kind of code that you use when writing any other Ruby object. You can put methods into objects and use those if you like too!
+
+Test Matching in Plain Ruby
+-----------
+
+When the `spec` block is evaluated the `return` value is used (in a very Ruby-like way) to determine if the test has passed or failed. Standard Ruby comparisons are your friend!
 
 Because there's no matchers and only one method there's no need for specialized reference documentation, but here are some ideas to get you going!
 
@@ -198,8 +234,8 @@ end
 ```
 
 If there's no error, then Uspec will see the result of the method call (whatever it might be).
-If the wrong Exception is raised, then because of reraising (by just calling `raise` without parameters),
-Ruby will dutifully pass along the error for Uspec to display.
+
+If the wrong Exception is raised, then because of reraising (by just calling `raise` without parameters), Ruby will dutifully pass along the error for Uspec to display.
 
 Mocks, Spies, Stubs, and More!
 -----------------------
@@ -218,4 +254,4 @@ Contributing
 Author
 ------
 
-> Anthony M. Cook 2013-2021
+> Anthony M. Cook 2013-2024

data/lib/uspec/cli.rb

@@ -8,9 +8,9 @@ class Uspec::CLI
     @paths = args
     @pwd = Pathname.pwd.freeze
     @stats = Uspec::Stats.new
-    @dsl = Uspec::DSL.new self
+    @harness = Uspec::Harness.new self
   end
-  attr :stats, :dsl
+  attr :stats, :harness
 
   def usage
     warn "uspec v#{::Uspec::VERSION} - minimalistic ruby testing framework"
@@ -74,7 +74,7 @@ class Uspec::CLI
       end
     elsif path.exist? then
       puts "#{path.basename path.extname}:"
-      dsl.instance_eval(path.read, path.to_s)
+      harness.define.instance_eval(path.read, path.to_s)
     else
       warn "path not found: #{path}"
     end
@@ -101,9 +101,9 @@ class Uspec::CLI
     MSG
     puts
     warn message
-    stats.failure << Uspec::Result.new(message, error, caller)
+    stats << Uspec::Result.new(message, error, caller)
 
-    dsl.__uspec_cli.handle_interrupt! error
+    handle_interrupt! error
   end
 
 end

data/lib/uspec/define.rb

@@ -0,0 +1,12 @@
+module Uspec
+  class Define
+
+    def initialize harness
+      @__uspec_harness = harness
+    end
+
+    def spec description, &block
+      @__uspec_harness.spec_eval description, &block
+    end
+  end
+end

data/lib/uspec/{dsl.rb → harness.rb}

@@ -2,48 +2,40 @@ require_relative "result"
 require_relative "spec"
 
 module Uspec
-  class DSL
+  class Harness
 
     def initialize cli
-      @__uspec_cli = cli
+      @cli = cli
+      @define = Uspec::Define.new self
     end
+    attr_accessor :cli, :define
 
-    def __uspec_cli
-      @__uspec_cli
+    def stats
+      cli.stats
     end
 
-    def __uspec_stats
-      @__uspec_cli.stats
-    end
-
-    def spec description, &block
+    def spec_eval description, &block
       state = 0
       print ' -- ', description
 
       if block then
         begin
           state = 1
-          raw_result = ::Uspec::Spec.new(self, description, &block).__uspec_block
+          raw_result = Uspec::Spec.new(self, description, &block).__uspec_block
           state = 2
         rescue Exception => raw_result
           state = 3
         end
       end
 
-      result = Result.new description, raw_result, caller
+      result = Uspec::Result.new description, raw_result, caller
 
       unless block then
         state = 4
         result.pending!
       end
 
-      if result.success?
-        __uspec_stats.success << result
-      elsif result.pending?
-        __uspec_stats.pending << result
-      else
-        __uspec_stats.failure << result
-      end
+      stats << result
 
       print ': ', result.pretty, "\n"
     rescue => error
@@ -57,9 +49,9 @@ module Uspec
       MSG
       puts
       warn message
-      __uspec_stats.failure << Uspec::Result.new(message, error, caller)
+      stats << Uspec::Result.new(message, error, caller)
     ensure
-      __uspec_cli.handle_interrupt! result.raw
+      cli.handle_interrupt! result.raw
       return [state, error, result, raw_result]
     end
   end

data/lib/uspec/result.rb

@@ -5,7 +5,7 @@ module Uspec
   class Result
     include Terminal
 
-    PREFIX = "#{Terminal.newline}#{Terminal.yellow}>\t#{Terminal.normal}"
+    PREFIX = "#{Uspec::Terminal.newline}#{Uspec::Terminal.yellow}>\t#{Uspec::Terminal.normal}"
 
     def initialize spec, raw, source
       @spec = spec

data/lib/uspec/spec.rb

@@ -3,31 +3,32 @@ require_relative "result"
 module Uspec
   class Spec
 
-    def initialize dsl, description, &block
+    def initialize harness, description, &block
       @__uspec_description = description
-      @__uspec_dsl = dsl
+      @__uspec_harness = harness
+      ns = harness.define
 
-      dsl.instance_variables.each do |name|
-        self.instance_variable_set(name, @__uspec_dsl.instance_variable_get(name)) unless name.to_s.include? '@__uspec'
+      ns.instance_variables.each do |name|
+        self.instance_variable_set(
+          name,
+          ns.instance_variable_get(name)
+        ) unless name.to_s.include? '@__uspec'
       end
 
-      dsl.methods(false).each do |name|
+      ns.methods(false).each do |name|
         self.define_singleton_method name do |*args, &block|
-          @__uspec_dsl.send name, *args, &block
+          ns.send name, *args, &block
         end unless name.to_s.include? '__uspec'
       end
 
       if block then
-      self.define_singleton_method :__uspec_block, &block
+        self.define_singleton_method :__uspec_block, &block
       else
         self.define_singleton_method :__uspec_block do
-          raise "Uspec: No block provided for `#{@__uspec_description}`"
+          raise NotImplementedError, "Uspec: No block provided for `#{@__uspec_description}`"
         end
       end
-    end
+    end # initialize
 
-    def spec description, &block
-      @__uspec_dsl.spec description, &block
-    end
   end
 end

data/lib/uspec/stats.rb

@@ -5,6 +5,16 @@ module Uspec
     end
     attr :success, :failure, :pending
 
+    def << result
+      if result.success?
+        self.success << result
+      elsif result.pending?
+        self.pending << result
+      else
+        self.failure << result
+      end
+    end
+
     def clear_results!
       @success = Array.new
       @failure = Array.new

data/lib/uspec/version.rb

@@ -1,3 +1,3 @@
 module Uspec
-  VERSION = '1.2.0'
+  VERSION = '1.3.0'
 end

data/lib/uspec.rb

@@ -1,5 +1,6 @@
 require_relative 'uspec/version'
-require_relative 'uspec/dsl'
+require_relative 'uspec/harness'
+require_relative 'uspec/define'
 require_relative 'uspec/stats'
 
 module Uspec

data/uspec/cli_spec.rb

@@ -1,5 +1,14 @@
 require_relative 'uspec_helper'
 
+def new_cli path  = '.'
+  Uspec::CLI.new(Array(path))
+end
+
+def run_specs path
+  new_cli(path).run_specs
+end
+
+
 spec 'shows usage' do
   output = capture do
     exec 'bin/uspec -h'
@@ -9,73 +18,61 @@ spec 'shows usage' do
 end
 
 spec 'runs a path of specs' do
-  output = capture do
-    path = Pathname.new(__FILE__).parent.parent.join('example_specs').to_s
-    Uspec::CLI.new(Array(path)).run_specs
+  output = outstr do
+    run_specs exdir.to_s
   end
 
   output.include?('I love passing tests') || output
 end
 
 spec 'runs an individual spec' do
-  output = capture do
-    path =  Pathname.new(__FILE__).parent.parent.join('example_specs', 'example_spec.rb').to_s
-    Uspec::CLI.new(Array(path)).run_specs
+  output = outstr do
+    run_specs exdir.join('example_spec.rb').to_s
   end
 
   output.include?('I love passing tests') || output
 end
 
 spec 'broken requires in test files count as test failures' do
-  path =  Pathname.new(__FILE__).parent.join('test_specs', 'broken_require_spec')
+  output, status = Open3.capture2e "#{root}/bin/uspec #{testdir.join('broken_require_spec')}"
 
-  output = capture do
-    exec "bin/uspec #{path}"
-  end
-
-  $?.exitstatus == 1 || $?
+  status.exitstatus == 1 || status
 end
 
 spec 'displays information about test file with broken require' do
-  path =  Pathname.new(__FILE__).parent.join('test_specs', 'broken_require_spec')
-
-  output = capture do
-    exec "bin/uspec #{path}"
-  end
+  output, status = Open3.capture2e "#{root}/bin/uspec #{testdir.join('broken_require_spec')}"
 
   output.include?('cannot load such file') || output
 end
 
 spec 'exit code is the number of failures' do
   expected = 50
-  output = capture do
-    @__uspec_dsl.__uspec_stats.clear_results! # because we're forking, we will have a copy of the current results
+  cli = new_cli
 
+  outstr do
     expected.times do |count|
-      spec "fail ##{count + 1}" do
+      cli.harness.define.spec "fail ##{count + 1}" do
         false
       end
     end
-
-    exit @__uspec_dsl.__uspec_cli.exit_code
   end
-  actual = $?.exitstatus
 
+  actual = cli.exit_code
   actual == expected || output
 end
 
 spec 'when more than 255 failures, exit status is 255' do
-  output = capture do
-    @__uspec_dsl.__uspec_stats.clear_results! # because we're forking, we will have a copy of the current results
+  expected = 255
+  cli = new_cli
 
+  output = outstr do
     500.times do
-      spec 'fail' do
+      cli.harness.define.spec 'fail' do
         false
       end
     end
-
-    exit @__uspec_dsl.__uspec_cli.exit_code
   end
 
-  $?.exitstatus == 255 || [$?, output]
+  actual = cli.exit_code
+  actual == expected || [$?, output]
 end

data/uspec/dsl_spec.rb

@@ -1,8 +1,10 @@
 require_relative "uspec_helper"
 
 spec 'catches errors' do
-  output = capture do
-    spec 'exception' do
+  cli = new_cli
+
+  output = outstr do
+    cli.harness.define.spec 'exception' do
       raise 'test exception'
     end
   end
@@ -11,8 +13,10 @@ spec 'catches errors' do
 end
 
 spec 'catches even non-StandardError-subclass exceptions' do
-  output = capture do
-    spec 'not implemented error' do
+  cli = new_cli
+
+  output = outstr do
+    cli.harness.define.spec 'not implemented error' do
       raise ::NotImplementedError, 'test exception'
     end
   end
@@ -21,9 +25,9 @@ spec 'catches even non-StandardError-subclass exceptions' do
 end
 
 spec 'Uspec exits when sent a termination signal' do
-  path =  Pathname.new(__FILE__).parent.join('test_specs', 'kill_this_spec')
+  path = testdir.join('kill_this_spec')
 
-  stdin, allout, thread = Open3.popen2e "uspec/test_specs/kill_this_script.sh \"#{path}\""
+  stdin, allout, thread = Open3.popen2e "#{testdir}/kill_this_script.sh \"#{path}\""
   stdin.close
   output = allout.read
 
@@ -40,8 +44,10 @@ spec 'Uspec exits when sent a termination signal' do
 end
 
 spec 'complains when spec block returns non boolean' do
-  output = capture do
-    spec 'whatever' do
+  cli = new_cli
+
+  output = outstr do
+    cli.harness.define.spec 'whatever' do
       "string"
     end
   end
@@ -50,10 +56,10 @@ spec 'complains when spec block returns non boolean' do
 end
 
 spec 'marks test as pending when no block supplied' do
-  path =  Pathname.new(__FILE__).parent.join('test_specs', 'pending_spec')
+  path = testdir.join('pending_spec')
 
   output = capture do
-    exec "bin/uspec #{path}"
+    exec "#{root}/bin/uspec #{path}"
   end
 
   output.include?('1 pending') || output
@@ -64,40 +70,40 @@ spec 'should not define DSL methods on arbitrary objects' do
 end
 
 spec 'when return used in spec, capture it as an error' do
-  path =  Pathname.new(__FILE__).parent.join('test_specs', 'return_spec')
+  path = testdir.join('return_spec')
 
   output = capture do
-    exec "bin/uspec #{path}"
+    exec "#{root}/bin/uspec #{path}"
   end
 
   output.include?('Invalid return') || output.include?('Spec did not return a boolean value') || output
 end
 
 spec 'when break used in spec, capture it as an error' do
-  path =  Pathname.new(__FILE__).parent.join('test_specs', 'break_spec')
+  path = testdir.join('break_spec')
 
   output = capture do
-    exec "bin/uspec #{path}"
+    exec "#{root}/bin/uspec #{path}"
   end
 
   output.include?('Invalid break') || output.include?('Spec did not return a boolean value') || output
 end
 
 spec 'when instance variables are defined in the DSL instance, they are available in the spec body' do
-  path =  Pathname.new(__FILE__).parent.join('test_specs', 'ivar_spec')
+  path = testdir.join('ivar_spec')
 
   output = capture do
-    exec "bin/uspec #{path}"
+    exec "#{root}/bin/uspec #{path}"
   end
 
   output.include?('1 successful') || output
 end
 
 spec 'when methods are defined in the DSL instance, they are available in the spec body' do
-  path =  Pathname.new(__FILE__).parent.join('test_specs', 'method_spec')
+  path = testdir.join('method_spec')
 
   output = capture do
-    exec "bin/uspec #{path}"
+    exec "#{root}/bin/uspec #{path}"
   end
 
   output.include?('1 successful') || output

data/uspec/stats_spec.rb

@@ -1,12 +1,12 @@
 require_relative 'uspec_helper'
 
 spec 'stats can be inspected' do
-  actual = @__uspec_dsl.__uspec_stats.inspect
+  actual = @__uspec_harness.stats.inspect
   actual.include?("failure") || actual
 end
 
 spec 'stats inspect does not have any stray whitespace' do
-  output = @__uspec_dsl.__uspec_stats.inspect
-  match = output.match(/  |\n/)
-  match == nil
+  output = @__uspec_harness.stats.inspect
+  match = output.match /(.*(?:  |\n))/m
+  match == nil || match
 end

data/uspec/test_specs/kill_this_script.sh

@@ -6,22 +6,21 @@ THISDIR="$(realpath "$(dirname "$0")")"
 ROOTDIR="$(realpath "$THISDIR/../..")"
 
 path="$1"
-name="$(basename "$path")"
 
 if ! [ -f "$path" ]; then
   echo "file not found: $path"
   exit 255
 fi
 
-mkdir -v -p tmp
 if command_exists bundle; then
-  bundle exec "$ROOTDIR/bin/uspec" "$path" > "tmp/$name.output" 2>&1 &
+  echo running with bundler
+  bundle exec "$ROOTDIR/bin/uspec" "$path" 2>&1 &
+  pid="$!"
 else
-  "$ROOTDIR/bin/uspec" "$path" > "tmp/$name.output" 2>&1 &
+  echo running directly
+  "$ROOTDIR/bin/uspec" "$path" 2>&1 &
+  pid="$!"
 fi
 
-pid=$!
 sleep 1
-kill $pid
-cat "tmp/$name.output"
-rm -v "tmp/$name.output"
+kill "$pid"

data/uspec/uspec_helper.rb

@@ -4,6 +4,7 @@ rescue LoadError => err
   nil
 end
 require 'open3'
+require 'stringio'
 
 require_relative '../lib/uspec'
 extend Uspec
@@ -24,3 +25,37 @@ def capture
 
   output
 end
+
+def outstr
+  old_stdout = $stdout
+  old_stderr = $stderr
+
+  outio = StringIO.new
+  $stdout = outio
+
+  errio = StringIO.new
+  $stderr = errio
+
+  val = yield
+
+  outio.string + errio.string
+ensure
+  $stdout = old_stdout
+  $stderr = old_stderr
+end
+
+def root
+  Pathname.new(__FILE__).parent.parent
+end
+
+def exdir
+  root.join('example_specs')
+end
+
+def specdir
+  root.join('uspec')
+end
+
+def testdir
+  specdir.join('test_specs')
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: uspec
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Anthony M. Cook
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-02-22 00:00:00.000000000 Z
+date: 2024-02-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: that_object_is_so_basic
@@ -49,7 +49,8 @@ files:
 - example_specs/spec_helper.rb
 - lib/uspec.rb
 - lib/uspec/cli.rb
-- lib/uspec/dsl.rb
+- lib/uspec/define.rb
+- lib/uspec/harness.rb
 - lib/uspec/result.rb
 - lib/uspec/spec.rb
 - lib/uspec/stats.rb