blackstart 0.2.0 → 0.6.0

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2024 Aaron Beckerman
+Copyright (c) 2024-2025 Aaron Beckerman
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in

data/README.txt

@@ -2,82 +2,99 @@ Blackstart
 
 Blackstart is a small, subdued library for automated testing in Ruby. It
 doesn't depend on anything beyond the Ruby platform and doesn't modify the
-environment outside its conventional namespace. It's tested with a primitive
-program, not via another automated-testing library.
+environment beyond its conventional namespace. It's tested with a primitive
+program, not via an automated-testing library.
 
-The blackstart is a small, subdued bird that eats bugs. A black start is when a
-power plant starts up without relying on the electrical grid.
+The blackstart is a small, subdued bird that eats bugs. A black start is when
+an inactive power plant restarts by means of an independent power source rather
+than the electrical grid.
 
 Here's an example of a test program that uses Blackstart:
 
   require "blackstart"
 
-  exit Blackstart.run Blackstart.add { |adder|
-    adder.call do
+  exit Blackstart.run [
+    proc {
       unless "Hello, World!" == ["He", "", "o, Wor", "d!"].join("l")
         raise "join did not work as expected"
       end
-    end
+    },
 
-    adder.call do
+    proc {
       unless "sample" == "simple".gsub(/i/, "a")
         raise "gsub did not work as expected"
       end
-    end
-  }
-
-Blackstart.add adds procs to a collection and returns that collection. In the
-example, each proc is designed to run a test and, if it fails, raise an error
-to signal this.
+    }
+  ]
 
 Blackstart.run runs a sequence of tests and reports information about any that
-fail -- that is, any that raise an error. In the example, failure information
-would be written to the standard output stream. It returns false if there were
-failures; otherwise, it returns true.
+fail. It returns false if there were failures, true otherwise.
+
+An array of procs is an easy way to represent a sequence of tests. In general,
+the sequence can be any object that responds to an each message in the
+conventional way and each test object in the sequence can be any object that
+(1) is a proc or converts to one via to_proc and (2) converts to a string via
+to_s.
+
+Each test is run by converting the test object to a proc if necessary and then
+calling it in the context of a new instance of Blackstart::Scratchpad; if and
+only if this raises an error (any exception that's a kind of StandardError),
+Blackstart.run interprets it as a failed test.
+
+After each test failure, Blackstart.run sends a puts message with failure
+information to its second parameter, which is $stdout by default. The failure
+information includes a description of the test (the test object converted to a
+string) and a description of the error raised (its class, message, and
+backtrace).
 
-The library provides little beyond this, but it's easy to do relatively
-sophisticated things with it. Some examples follow.
+The library provides little beyond this, but it's easy to do sophisticated
+things with it. Some examples follow.
 
 
 - Exiting with the appropriate status
 
-Blackstart.run returns false if there were any failures; otherwise, it returns
-true. If you use this as the argument to Kernel#exit, your test program will
-exit with a successful status only if there were no failures.
+You may want your test program to exit with a successful status only if there
+were no failures, perhaps so it can work as part of a testing script. You can
+do this by using the object returned by Blackstart.run as the argument to
+Kernel#exit. Blackstart.run returns false if there were failures, true
+otherwise.
 
 
 - Defining helpers
 
-You may want all your tests to be able to assert something, generate test data,
+You may want to enable all your tests to assert something, generate test data,
 or perform some other task by sending a message. You could implement this
 statelessly in a singleton object or all instances of Object, for example, but
-there's another option that may be more convenient. Blackstart.run calls each
-test proc in the context of a new Blackstart::Context instance. You can define
-instance methods in that class like this:
+there's another option that may be more convenient. When Blackstart.run calls a
+test proc, it sets the self object to a new instance of Blackstart::Scratchpad.
+You can define instance methods in that class. For example:
 
-  class Blackstart::Context
+  class Blackstart::Scratchpad
     def assert boolean
       raise "assertion failed" unless boolean
     end
 
     def make_products
       @cabbage = { :description => "head of cabbage", :price => 125 }
-      @orange = { :description => "Cara cara navel orange", :price => 100 }
+      @orange = { :description => "Cara Cara navel orange", :price => 100 }
       nil
     end
   end
 
-All of your tests will be able to use them by sending messages to self. These
-methods can see and modify the test's state, which is disposable: it will be
-discarded after the test is complete and so will not affect later tests.
+All your test procs can use them by sending messages to self. These methods,
+like the test proc itself, can see and modify instance variables and other
+elements of the scratchpad's state. The scratchpad is disposable:
+Blackstart.run discards it after the test is complete.
 
 
 - Running code before and after each test
 
-You can run code before and after each test by defining a custom
-Blackstart::Context#instance_exec. For example:
+You may want to run code before and after each test -- for example, to create
+objects needed in tests or clean up resources without requiring every test to
+do these explicitly. You can do this by defining a custom
+Blackstart::Scratchpad#instance_exec. For example:
 
-  class Blackstart::Context
+  class Blackstart::Scratchpad
     def instance_exec(*)
       puts "before test"
       @variable = "example"
@@ -87,66 +104,73 @@ Blackstart::Context#instance_exec. For example:
     end
   end
 
+Use this hack with care because the test proc could send instance_exec messages
+to self.
+
 
 - Building a test collection in stages
 
-You can build your collection of test objects in stages and run it at the end.
-For example:
+You may want to build a test collection in stages rather than all at once. This
+can be done straightforwardly:
 
   require "blackstart"
 
-  TEST_OBJECTS = []
+  TESTS = []
 
-  Blackstart.add TEST_OBJECTS do |adder|
-    adder.call do
+  TESTS.concat [
+    proc {
       unless "Hello, World!" == ["He", "", "o, Wor", "d!"].join("l")
         raise "join did not work as expected"
       end
-    end
-  end
+    }
+  ]
 
-  Blackstart.add TEST_OBJECTS do |adder|
-    adder.call do
+  TESTS.concat [
+    proc {
       unless "sample" == "simple".gsub(/i/, "a")
         raise "gsub did not work as expected"
       end
-    end
-  end
+    }
+  ]
 
-  exit Blackstart.run TEST_OBJECTS
+  exit Blackstart.run TESTS
 
-This makes it straightforward to define your tests in multiple files that you
-load in your test program.
+This pattern is useful if you want to define your tests in multiple files: you
+create a collection with an agreed-upon name, load multiple files, each of
+which adds test objects to that collection, and then run all the tests.
 
 
 - Running tests in random order
 
+To check if you have any tests that depend on other tests having run, or not
+having run, earlier, you may want to run your tests in random order.
 Blackstart.run runs a sequence of tests in order, but you can pass it a
-randomly-ordered sequence. Array#shuffle may be helpful for this. If you do
-this, you may also want to print the random seed at the start of your program
-so you can re-run your tests in the same order.
+randomly-ordered sequence. Array#shuffle may be helpful for this. If you use
+Array#shuffle or something similar, you may also want to print the random seed
+just before the tests are shuffled so you can rerun your tests in the same
+order by setting the random seed.
 
 
 - Reporting detailed test descriptions
 
-After a test fails, Blackstart.run writes a description of the test to the
-output stream. It gets this description by converting the test object to a
-string. When the test object is an instance of Proc, which is what
-Blackstart.add normally produces, this string typically includes the file path
-and line number where it was defined: helpful, but it won't be immediately
-clear what was being tested.
+After a test fails, Blackstart.run writes a string describing the test to the
+output stream. It gets this string by sending a to_s message to the test
+object. When the test object is an instance of Proc, the returned string
+typically includes the file path and line number where it was defined: helpful,
+but it won't be immediately clear what was being tested.
 
-You can improve this by making your own test objects instead of using
-Blackstart.add. Blackstart.run does not strictly need a sequence of Proc
-instances; it only needs a sequence of objects that convert to Proc instances
-in response to to_proc messages. Your custom test objects can respond to to_s
-with detailed descriptions instead of mere file paths and line numbers.
+You can improve this by designing your own test objects. Blackstart.run does
+not strictly need a sequence of procs; it also works with a sequence of objects
+that convert to procs in response to to_proc messages. Your custom test objects
+can respond to to_s with detailed descriptions instead of mere file paths and
+line numbers.
 
 
 - Handling failures differently
 
 Blackstart.run handles each failure by sending a puts message to the output
-stream, one of its parameters. By default, this is $stdout, so the default
-behavior is to print unadorned failure information to standard output. But you
-can specify any object as the output stream -- even if it's not really a stream
--- allowing you to handle failure information however you want.
+stream, one of its parameters, with failure information. By default, the output
+stream is $stdout, so the default behavior is to print unadorned failure
+information to standard output. But you can specify any object as the output
+stream -- even if it's not really a stream -- allowing you to handle failure
+information however you want.

data/lib/blackstart.rb

@@ -1,87 +1,70 @@
 ##
-# This module provides facilities for defining and running automated tests.
+# This module provides facilities for running automated tests.
 
 module Blackstart
 
   ##
-  # Calls the block and returns a string describing the error raised, if any.
+  # Yields to the block and returns a string describing the error raised, if
+  # any.
   #
-  # In detail: This method sends call with no arguments to the object
-  # representing the block. If that raises an error -- that is, an exception
-  # whose class is StandardError or a descendent of StandardError -- this
-  # method creates a string describing that error and returns it; the
-  # description includes the error's class, message, and backtrace (if any). If
-  # sending the message raises any other exception, this method raises that
-  # exception. If sending the message does not raise an exception, this method
-  # returns nil.
+  # In detail: This method yields to the block with no arguments. If that
+  # raises an error -- meaning an exception whose class is StandardError or a
+  # descendant of StandardError -- this method attempts to make and return a
+  # string describing that error; the description consists of the error's
+  # class, message, and backtrace (if any). If an exception is raised while
+  # making an error description, this method raises that exception. If
+  # yielding to the block raises a non-error exception, this method raises that
+  # exception. If yielding to the block does not raise an exception, this
+  # method returns nil.
 
-  def self.vet &prc
-    prc.call
+  def self.vet
+    yield
     nil
-  rescue ::StandardError
+  rescue ::StandardError => e
     # Like IO#puts, separate lines with a line feed character rather than $\.
-    ["#{$!.class}: #{$!.message}"].concat($!.backtrace || []).join "\n"
+    ["#{e.class}: #{e.message}"].concat(e.backtrace || []).join "\n"
   end
 
   ##
-  # Allows the block to add procs to a collection, which it returns.
-  #
-  # In detail: This method sends call with one positional argument, an adder
-  # object, to the object representing the block, director. This block can send
-  # call messages to the adder to add objects representing the respective
-  # blocks to the collection, sink. With each sending of call, the object to be
-  # added will be either a proc (if call is sent with a block) or nil (if call
-  # is sent without a block). If any non-block arguments are sent with the call
-  # message, an exception is raised. To add the object, the adder sends a <<
-  # message to sink with the object as the positional argument and no other
-  # arguments. The adder returns nil in response to a call message if it
-  # returns at all. This method returns sink.
-  #
-  # By default, sink is a new empty array.
-
-  def self.add sink = [], &director
-    director.call ::Kernel.lambda { |&prc|
-      sink << prc
-      nil
-    }
-    sink
-  end
-
-  ##
-  # A class for the contexts (the self objects) of tests.
+  # A class for tests' disposable helper objects.
 
-  class Context
+  class Scratchpad
   end
 
   ##
-  # Runs the tests, writes any failure information to the output stream, and
+  # Runs tests, writes any failure information to the output stream, and
   # returns a boolean indicating whether there were no failures.
   #
-  # In detail: This method expects the sequence of test objects, source, to
-  # respond to an each message by yielding successive test objects to its
-  # block. Each test is run by converting the test object to a proc and calling
-  # it in the context of a new instance of Blackstart::Context. A failure is
-  # when the test raises an error (that is, an exception whose class is
-  # StandardError or a descendent of StandardError). After a failure, this
-  # method sends a puts message to the output stream, ostream, with these
-  # arguments (positional, in order): a string "FAILED TEST:", the test object
-  # converted to a string via to_s, a string "...ERROR:", a string describing
-  # the error, and an empty string. If a test raises any other exception, this
-  # method immediately raises that exception. After it has run all the tests
-  # and handled any failures, this method returns false if there were failures
-  # or true otherwise.
+  # In detail: This method sends an each message with a block to the sequence
+  # of test objects, source, expecting it to yield to the block once for each
+  # test object in the sequence with that test object as the first argument.
+  # Each test involves creating a new scratchpad -- an instance of
+  # Blackstart::Scratchpad -- and sending an instance_exec message to it with
+  # the test object as a block argument, which converts the test object to a
+  # proc via to_proc if it's not already a proc. The resulting proc is called
+  # with no arguments; the self object is set to the scratchpad. A failure is
+  # when the test (which includes any initial conversion to a proc) raises an
+  # error: an exception whose class is StandardError or a descendant of
+  # StandardError. After a failure, this method sends a puts message to the
+  # output stream, ostream, with these arguments (positional, in order): a
+  # string "FAILED TEST:"; the test object converted to a string via to_s; a
+  # string "...ERROR:"; a string combining the class, message, and backtrace of
+  # the error; and an empty string. If a test raises a non-error exception,
+  # this method immediately raises that exception. After it has run all the
+  # tests and handled any failures, this method returns false if there were
+  # failures, true otherwise. This method immediately raises any exception
+  # raised outside of a test.
   #
   # By default, ostream is $stdout.
 
   def self.run source, ostream = $stdout
     success = true
-    for tst in source
-      # Convert to a proc and create a context outside the vet block so that
-      # this method will raise any exception that results instead of
-      # potentially treating it as a test failure.
-      prc = ::Proc.new(&tst)
-      context = Context.new
-      if err_desc = vet { context.instance_exec(&prc) }
+    source.each do |tst|
+      # Create the scratchpad outside the vet block so that this method will
+      # raise any exception that results instead of potentially treating it as
+      # a test failure.
+      scratchpad = Scratchpad.new
+      if err_desc = vet { scratchpad.instance_exec(&tst) }
         success = false
         ostream.puts "FAILED TEST:", tst.to_s, "...ERROR:", err_desc.to_s, ""
       end

data/test/blackstart_test.rb

@@ -6,9 +6,8 @@ require "blackstart"
 # Blackstart should be a module.
 fail "" unless Module.equal? Blackstart.class
 
-# Blackstart should say it responds to vet, add, and run.
+# Blackstart should say it responds to vet and run.
 fail "" unless Blackstart.respond_to? :vet
-fail "" unless Blackstart.respond_to? :add
 fail "" unless Blackstart.respond_to? :run
 
 # Test Blackstart.vet:
@@ -27,10 +26,14 @@ else
   fail ""
 end
 
-# If sending call with no arguments to the block raises an error,
-# Blackstart.vet should return a new descriptive string.
+# If yielding to the block raises an error, Blackstart.vet should return a
+# string describing that error.
 class ::Object
-  fail "" unless /\ANoMethodError: / =~ Blackstart.vet
+  # Should return an error description when no block is given.
+  fail "" unless String.equal? Blackstart.vet.class
+
+  # Use frozen strings and backtrace arrays so that an exception will be raised
+  # if they're modified.
 
   e_class = Class.new StandardError
   def e_class.to_s
@@ -41,158 +44,73 @@ class ::Object
   def e_nil.backtrace
     nil
   end
-  fail "" unless "FakeError: a" == Blackstart.vet { ::Kernel.raise e_nil }
+  error = Blackstart.vet { ::Kernel.raise e_nil }
+  fail "" unless String.equal? error.class
+  fail "" unless "FakeError: a" == error
 
   e_empty = e_class.new "b".freeze
   def e_empty.backtrace
     [].freeze
   end
-  fail "" unless "FakeError: b" == Blackstart.vet { ::Kernel.raise e_empty }
+  error = Blackstart.vet { ::Kernel.raise e_empty }
+  fail "" unless String.equal? error.class
+  fail "" unless "FakeError: b" == error
 
   e_full = e_class.new "c".freeze
   def e_full.backtrace
     ["d".freeze, "e".freeze].freeze
   end
-  fail "" unless "FakeError: c\nd\ne" ==
-    Blackstart.vet { ::Kernel.raise e_full }
-end
-
-# If sending call with no arguments to the block raises a non-StandardError
-# exception, Blackstart.vet should not rescue it.
-class ::Object
-  non_standard_error = Class.new Exception
-  begin
-    Blackstart.vet { ::Kernel.raise non_standard_error }
-  rescue non_standard_error
-  else
-    fail ""
-  end
-end
-
-# If sending call with no arguments to the block does not raise an exception,
-# Blackstart.vet should return nil.
-fail "" unless nil.equal? Blackstart.vet { nil }
-fail "" unless nil.equal? Blackstart.vet { true }
-
-# Test Blackstart.add:
-
-# When there is no block, Blackstart.add should raise an exception.
-begin
-  Blackstart.add
-rescue NoMethodError
-else
-  fail ""
-end
-begin
-  Blackstart.add []
-rescue NoMethodError
-else
-  fail ""
-end
-
-# Blackstart.add should raise an exception if superfluous arguments are sent.
-begin
-  Blackstart.add [], "invalid"
-rescue ArgumentError
-else
-  fail ""
-end
-begin
-  Blackstart.add([], "invalid") {}
-rescue ArgumentError
-else
-  fail ""
-end
-
-# When no collection is specified and the block does nothing, Blackstart.add
-# should return an empty array.
-fail "" unless [] == Blackstart.add {}
-
-# When a collection is specified and the block tries to add to the collection,
-# Blackstart.add should add corresponding procs or nil to the collection by
-# sending <<.
-class ::Object
-  sink = [42]
-  prc1 = proc {}
-  prc2 = proc {}
-  retval = Blackstart.add sink do |adder|
-    adder.call(&prc1)
-    adder.call(&prc2)
-    adder.call
-  end
-  fail "" unless sink.equal? retval
-  fail "" unless [42, prc1, prc2, nil] == sink
+  error = Blackstart.vet { ::Kernel.raise e_full }
+  fail "" unless String.equal? error.class
+  fail "" unless "FakeError: c\nd\ne" == error
 end
 
-# When the block sends call to the adder with arguments other than a block, it
-# should raise an exception and not add anything to the collection.
+# If yielding to the block raises an error and that error raises an exception
+# when queried, Blackstart.vet should raise that second exception.
 class ::Object
-  sink = []
-  begin
-    Blackstart.add(sink) { |adder| adder.call("invalid") {} }
-  rescue ArgumentError
-  else
-    fail ""
+  e1 = StandardError.new
+  e2_class = Class.new StandardError
+  e1.instance_variable_set :@next_exception_class, e2_class
+  def e1.message
+    ::Kernel.raise @next_exception_class
   end
   begin
-    Blackstart.add(sink) { |adder| adder.call "invalid" }
-  rescue ArgumentError
+    Blackstart.vet { ::Kernel.raise e1 }
+  rescue e2_class
   else
     fail ""
   end
-  fail "" unless 0 == sink.length
-end
-
-# When Blackstart.add's block sends call to the adder and it returns, nil
-# should be the object it returns.
-class ::Object
-  retval_block = retval_no_block = true
-  Blackstart.add do |adder|
-    retval_block = adder.call {}
-    retval_no_block = adder.call
-  end
-  fail "" unless nil.equal? retval_block
-  fail "" unless nil.equal? retval_no_block
 end
 
-# In general, when there is a block that raises an exception, Blackstart.add
-# should not rescue it.
+# If yielding to the block raises a non-StandardError exception, Blackstart.vet
+# should raise it.
 class ::Object
-  e = StandardError.new
+  non_standard_error = Class.new Exception
   begin
-    Blackstart.add { ::Kernel.raise e }
-  rescue
-    fail "" unless e.equal? $!
+    Blackstart.vet { ::Kernel.raise non_standard_error }
+  rescue non_standard_error
   else
     fail ""
   end
 end
 
-# When there is a block that tries to add to the collection and the collection
-# responds to the << message by raising an exception, Blackstart.add should not
-# rescue it.
-begin
-  Blackstart.add(nil) { |adder| adder.call {} }
-rescue NoMethodError
-else
-  fail ""
-end
+# If yielding to the block does not raise an exception, Blackstart.vet should
+# return nil. The object returned shouldn't matter.
+fail "" unless nil.equal? Blackstart.vet { nil }
+fail "" unless nil.equal? Blackstart.vet { true }
 
-# When no collection is specified and the block tries to add to the collection,
-# Blackstart.add should append to a new array that gets returned.
-class ::Object
-  prc = proc {}
-  fail "" unless [prc] == Blackstart.add { |adder| adder.call(&prc) }
-end
+# Test Blackstart::Scratchpad:
 
-# Test Blackstart::Context:
+# Blackstart::Scratchpad.new should return an instance of
+# Blackstart::Scratchpad, which implies that Blackstart::Scratchpad should be a
+# class.
+fail "" unless Blackstart::Scratchpad.equal? Blackstart::Scratchpad.new.class
 
-# Blackstart::Context.new should return an instance of Blackstart::Context,
-# which implies that Blackstart::Context should be a class.
-fail "" unless Blackstart::Context.equal? Blackstart::Context.new.class
+# Blackstart::Scratchpad should not be frozen.
+fail "" if Blackstart::Scratchpad.frozen?
 
-# A new context should have no instance variables.
-fail "" unless 0 == Blackstart::Context.new.instance_variables.length
+# A new scratchpad should have no instance variables.
+fail "" unless 0 == Blackstart::Scratchpad.new.instance_variables.length
 
 # Test Blackstart.run:
 
@@ -200,7 +118,7 @@ fail "" unless 0 == Blackstart::Context.new.instance_variables.length
 # return the appropriate object based on the behavior of the tests.
 class ::Object
   begin
-    # Set $stdout to a test spy and set it back in the ensure clause.
+    # Set $stdout to a test spy and restore it in the ensure clause.
     original_stdout = $stdout
     spy_stdout = $stdout.clone
     spy_stdout.instance_variable_set :@_test_calls, stdout_calls = []
@@ -210,155 +128,235 @@ class ::Object
     end
     $stdout = spy_stdout
 
-    # No tests.
-    source = [].freeze
-    fail "" unless true.equal? Blackstart.run(source, Object.new)
+    invalid_ostream = Object.new
+    def invalid_ostream.puts(*)
+      ::Kernel.raise ::NoMethodError
+    end
+
+    # When there are no tests, Blackstart.run should not notify the output
+    # stream of any failures.
+    source = []
+    fail "" unless true.equal? Blackstart.run(source, invalid_ostream)
     fail "" unless true.equal? Blackstart.run(source, spy_stdout)
     fail "" unless true.equal? Blackstart.run(source)
     fail "" unless 0 == stdout_calls.length
 
-    # Tests that do not raise exceptions.
-    source = [proc {}, proc { 42 }].freeze
-    fail "" unless true.equal? Blackstart.run(source, Object.new)
+    # When there are tests but none raise exceptions, Blackstart.run should not
+    # notify the output stream of any failures. The objects returned by the
+    # test procs shouldn't affect Blackstart.run's behavior.
+    source = [proc {}, proc { 42 }]
+    fail "" unless true.equal? Blackstart.run(source, invalid_ostream)
     fail "" unless true.equal? Blackstart.run(source, spy_stdout)
     fail "" unless true.equal? Blackstart.run(source)
     fail "" unless 0 == stdout_calls.length
 
-    # Define some example test objects.
-    e_class = Class.new StandardError
+    # Define some test objects. Freeze them, the strings to which they convert,
+    # some exception details, and the strings to which the exception classes
+    # convert to check that they don't get modified.
+    e_class = Class.new StandardError do
+      def backtrace
+        ["line1".freeze, "line2".freeze].freeze
+      end
+    end
     def e_class.to_s
-      "FakeError"
+      "FakeError".freeze
     end
-    fail_prc1 = proc { ::Kernel.raise e_class, "fake message 1" }
+    fail_prc1 = proc { ::Kernel.raise e_class, "fake message 1".freeze }
     def fail_prc1.to_s
-      "to_s 1"
+      "to_s 1".freeze
     end
+    fail_prc1.freeze
+    pass_prc = proc {}.freeze
     fail_prc2 = Object.new # Not a Proc instance, but converts to one.
     fail_prc2.instance_variable_set :@_test_e_class, e_class
     def fail_prc2.to_proc
       e_class = @_test_e_class
-      ::Proc.new { ::Kernel.raise e_class, "fake message 2" }
+      ::Proc.new { ::Kernel.raise e_class, "fake message 2".freeze }.freeze
     end
     def fail_prc2.to_s
-      "to_s 2"
+      "to_s 2".freeze
     end
-    pass_prc = proc {}
-
-    # A mix of tests that raise errors and tests that return.
-    source = [fail_prc1, fail_prc2, pass_prc].freeze
-
-    # Output stream that does not conform to the expected interface. (And in
-    # general, the only exceptions Blackstart.run should rescue are
-    # StandardError exceptions raised by tests.)
-    begin
-      Blackstart.run source, Object.new
-    rescue NoMethodError
-    else
-      fail ""
+    fail_prc2.freeze
+    non_prc = Object.new # Does not convert to a proc.
+    def non_prc.to_proc
+      ::Kernel.raise ::NoMethodError
     end
-    fail "" unless 0 == stdout_calls.length
+    def non_prc.to_s
+      "to_s 3".freeze
+    end
+    non_prc.freeze
+    bad_prc = Object.new # Pretends to convert to a proc but doesn't.
+    def bad_prc.to_proc
+      0
+    end
+    def bad_prc.to_s
+      "to_s 4".freeze
+    end
+    bad_prc.freeze
+
+    # A mix of tests that raise errors and tests that return. Freeze the array
+    # to check that it's not being modified.
+    source = [fail_prc1, pass_prc, fail_prc2, non_prc, bad_prc].freeze
 
-    # Output stream that conforms to the expected interface.
+    # An output stream that conforms to the expected interface and does not
+    # raise an exception should receive all failure information.
     spy_ostream = Object.new
     spy_ostream.instance_variable_set :@_test_calls, calls = []
     def spy_ostream.puts *args
       @_test_calls << args
-      nil
+      # A real standard output stream would return nil here (and spy_stdout
+      # does that), but Blackstart.run's behavior should not be affected by the
+      # returned object. Returning this unusual object tests that.
+      ::Object.new
     end
+    # Freeze the output stream to check that it's not being modified.
+    spy_ostream.freeze
     fail "" unless false.equal? Blackstart.run(source, spy_ostream)
     fail "" unless 0 == stdout_calls.length
-    fail "" unless 2 == calls.length
+    fail "" unless 4 == calls.length
     fail "" unless 5 == calls[0].length
+    fail "" unless calls[0].all? { |o| ::String.equal? o.class }
     fail "" unless "FAILED TEST:" == calls[0][0]
     fail "" unless "to_s 1" == calls[0][1]
     fail "" unless "...ERROR:" == calls[0][2]
-    fail "" unless /\AFakeError: fake message 1$/ =~ calls[0][3]
+    fail "" unless "FakeError: fake message 1\nline1\nline2" == calls[0][3]
     fail "" unless "" == calls[0][4]
     fail "" unless 5 == calls[1].length
+    fail "" unless calls[1].all? { |o| ::String.equal? o.class }
     fail "" unless "FAILED TEST:" == calls[1][0]
     fail "" unless "to_s 2" == calls[1][1]
     fail "" unless "...ERROR:" == calls[1][2]
-    fail "" unless /\AFakeError: fake message 2$/ =~ calls[1][3]
+    fail "" unless "FakeError: fake message 2\nline1\nline2" == calls[1][3]
     fail "" unless "" == calls[1][4]
-    spy_ostream = calls = nil
-
-    # Default output stream.
+    fail "" unless 5 == calls[2].length
+    fail "" unless calls[2].all? { |o| ::String.equal? o.class }
+    fail "" unless "FAILED TEST:" == calls[2][0]
+    fail "" unless "to_s 3" == calls[2][1]
+    fail "" unless "...ERROR:" == calls[2][2]
+    # (No need to check the error description.)
+    fail "" unless "" == calls[2][4]
+    fail "" unless 5 == calls[3].length
+    fail "" unless calls[3].all? { |o| ::String.equal? o.class }
+    fail "" unless "FAILED TEST:" == calls[3][0]
+    fail "" unless "to_s 4" == calls[3][1]
+    fail "" unless "...ERROR:" == calls[3][2]
+    # (No need to check the error description.)
+    fail "" unless "" == calls[3][4]
+
+    # The faked standard output stream.
     stdout_calls.clear
     fail "" unless false.equal? Blackstart.run(source)
-    fail "" unless 2 == stdout_calls.length
+    fail "" unless 4 == stdout_calls.length
     fail "" unless 5 == stdout_calls[0].length
+    fail "" unless stdout_calls[0].all? { |o| ::String.equal? o.class }
     fail "" unless "FAILED TEST:" == stdout_calls[0][0]
     fail "" unless "to_s 1" == stdout_calls[0][1]
     fail "" unless "...ERROR:" == stdout_calls[0][2]
-    fail "" unless /\AFakeError: fake message 1$/ =~ stdout_calls[0][3]
+    fail "" unless "FakeError: fake message 1\nline1\nline2" ==
+      stdout_calls[0][3]
     fail "" unless "" == stdout_calls[0][4]
     fail "" unless 5 == stdout_calls[1].length
+    fail "" unless stdout_calls[1].all? { |o| ::String.equal? o.class }
     fail "" unless "FAILED TEST:" == stdout_calls[1][0]
     fail "" unless "to_s 2" == stdout_calls[1][1]
     fail "" unless "...ERROR:" == stdout_calls[1][2]
-    fail "" unless /\AFakeError: fake message 2$/ =~ stdout_calls[1][3]
+    fail "" unless "FakeError: fake message 2\nline1\nline2" ==
+      stdout_calls[1][3]
     fail "" unless "" == stdout_calls[1][4]
+    fail "" unless 5 == stdout_calls[2].length
+    fail "" unless stdout_calls[2].all? { |o| ::String.equal? o.class }
+    fail "" unless "FAILED TEST:" == stdout_calls[2][0]
+    fail "" unless "to_s 3" == stdout_calls[2][1]
+    fail "" unless "...ERROR:" == stdout_calls[2][2]
+    # (No need to check the error description.)
+    fail "" unless "" == stdout_calls[2][4]
+    fail "" unless 5 == stdout_calls[3].length
+    fail "" unless stdout_calls[3].all? { |o| ::String.equal? o.class }
+    fail "" unless "FAILED TEST:" == stdout_calls[3][0]
+    fail "" unless "to_s 4" == stdout_calls[3][1]
+    fail "" unless "...ERROR:" == stdout_calls[3][2]
+    # (No need to check the error description.)
+    fail "" unless "" == stdout_calls[3][4]
     stdout_calls.clear
 
-    # Test that raises a non-StandardError exception. (And in general, the only
-    # exceptions Blackstart.run should rescue are StandardError exceptions
-    # raised by tests.)
-    non_standard_error = Class.new Exception
-    source = [proc { ::Kernel.raise non_standard_error }]
+    # An output stream that raises an exception when notified of a failure
+    # should cause Blackstart.run to raise that exception and stop processing
+    # tests. (In general, the only exceptions Blackstart.run should rescue are
+    # StandardError exceptions raised by tests.)
+    second_test_run = false
+    source = [proc { ::Kernel.raise "" }, proc { second_test_run = true }]
     begin
-      Blackstart.run source, spy_stdout
-    rescue non_standard_error
+      Blackstart.run source, invalid_ostream
+    rescue NoMethodError
     else
       fail ""
     end
+    fail "" if second_test_run
     fail "" unless 0 == stdout_calls.length
 
-    # Test sequence that does not conform to the interface. (And in general,
-    # the only exceptions Blackstart.run should rescue are StandardError
-    # exceptions raised by tests.)
+    # When a test raises a non-StandardError exception, Blackstart.run should
+    # raise that exception and stop processing tests. (In general, the only
+    # exceptions Blackstart.run should rescue are StandardError exceptions
+    # raised by tests.)
+    second_test_run = false
+    non_standard_error = Class.new Exception
+    source = [proc { ::Kernel.raise non_standard_error },
+      proc { second_test_run = true }]
     begin
-      Blackstart.run nil, spy_stdout
-    rescue NoMethodError
+      Blackstart.run source, spy_stdout
+    rescue non_standard_error
     else
       fail ""
     end
+    fail "" if second_test_run
     fail "" unless 0 == stdout_calls.length
 
-    # Test sequences containing objects that do not convert to procs (and do
-    # not pretend to) and objects that pretend to convert to procs but do not.
-    # (And in general, the only exceptions Blackstart.run should rescue are
+    # When the test sequence does not conform to the interface and raises an
+    # exception during iteration, Blackstart.run should raise that exception.
+    # (In general, the only exceptions Blackstart.run should rescue are
     # StandardError exceptions raised by tests.)
-    source = [nil]
-    begin
-      Blackstart.run source, spy_stdout
-    rescue ArgumentError
-    else
-      fail ""
+    source = Object.new
+    def source.each(*)
+      ::Kernel.raise ::NoMethodError
     end
-    source = [0]
     begin
       Blackstart.run source, spy_stdout
-    rescue TypeError
+    rescue NoMethodError
     else
       fail ""
     end
-    bad_to_proc = Object.new
-    def bad_to_proc.to_proc
-      nil
+    fail "" unless 0 == stdout_calls.length
+
+    # When a test fails and converting the test object to a string raises an
+    # exception, Blackstart.run should raise that exception and stop processing
+    # tests. (In general, the only exceptions Blackstart.run should rescue are
+    # StandardError exceptions raised by tests.)
+    second_test_run = false
+    no_desc = proc { ::Kernel.raise "" }
+    def no_desc.to_s
+      ::Kernel.raise ::NoMethodError
     end
-    source = [bad_to_proc]
+    source = [no_desc, proc { second_test_run = true }]
     begin
       Blackstart.run source, spy_stdout
-    rescue TypeError
+    rescue NoMethodError
     else
       fail ""
     end
+    fail "" if second_test_run
     fail "" unless 0 == stdout_calls.length
   ensure
     $stdout = original_stdout
   end
 end
 
+# Blackstart.run should run tests in order.
+class ::Object
+  data = []
+  Blackstart.run [proc { data << 1 }, proc { data << 2 }], nil
+  fail "" unless [1, 2] == data
+end
+
 # Blackstart.run should call each test proc with no arguments.
 class ::Object
   args = nil
@@ -369,14 +367,55 @@ class ::Object
   fail "" unless [] == args
 end
 
-# Blackstart.run should call each test proc in the context of a unique instance
-# of Blackstart::Context.
+# Blackstart.run should work with any source that responds to each. The object
+# returned in response to the each message should not affect Blackstart.run's
+# behavior.
 class ::Object
-  context1 = context2 = nil
-  Blackstart.run [proc { context1 = self }, proc { context2 = self }], nil
-  fail "" unless Blackstart::Context.equal? context1.class
-  fail "" unless Blackstart::Context.equal? context2.class
-  fail "" if context1.equal? context2
+  source = Object.new
+  def source.each
+    ran = false
+    yield proc { ran = true }
+    @ran = ran
+    self
+  end
+  fail "" unless true.equal? Blackstart.run(source, nil)
+  fail "" unless source.instance_variable_get :@ran
+
+  source = Object.new
+  def source.each
+    yield proc {}
+    nil
+  end
+  fail "" unless true.equal? Blackstart.run(source, nil)
+end
+
+# Blackstart.run should send exactly one each message to the source.
+class ::Object
+  source = Object.new
+  source.instance_variable_set :@count, 0
+  def source.each
+    @count += 1
+    self
+  end
+  Blackstart.run source, nil
+  fail "" unless 1 == source.instance_variable_get(:@count)
+end
+
+# When Blackstart.run calls a test proc, the self object should be a unique
+# instance of Blackstart::Scratchpad.
+class ::Object
+  sp1 = sp2 = nil
+  Blackstart.run [proc { sp1 = self }, proc { sp2 = self }], nil
+  fail "" unless Blackstart::Scratchpad.equal? sp1.class
+  fail "" unless Blackstart::Scratchpad.equal? sp2.class
+  fail "" if sp1.equal? sp2
+end
+
+# When Blackstart.run runs a test, the scratchpad should not be frozen.
+class ::Object
+  frozen = true
+  Blackstart.run [proc { frozen = frozen? }], nil
+  fail "" if frozen
 end
 
 # Blackstart.run should raise an exception if too few or too many non-block
@@ -387,11 +426,34 @@ rescue ArgumentError
 else
   fail ""
 end
-begin
-  Blackstart.run [], nil, "invalid"
-rescue ArgumentError
-else
-  fail ""
+class ::Object
+  source = []
+  begin
+    Blackstart.run source, nil, nil
+  rescue ArgumentError
+  else
+    fail ""
+  end
+end
+
+# The following section modifies the state of the library, so it must be run
+# after all the ordinary tests.
+
+# Blackstart.run should run each test by sending instance_exec to a scratchpad.
+class Blackstart::Scratchpad
+  def foo
+    2
+  end
+
+  def instance_exec(*)
+    @ivar = 1
+    super
+  end
+end
+class ::Object
+  result = nil
+  Blackstart.run [proc { result = [@ivar, foo()] }], nil
+  fail "" unless [1, 2] == result
 end
 
 # If this message doesn't get written, there was a problem.

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: blackstart
 version: !ruby/object:Gem::Version 
-  hash: 23
+  hash: 7
   prerelease: 
   segments: 
   - 0
-  - 2
+  - 6
   - 0
-  version: 0.2.0
+  version: 0.6.0
 platform: ruby
 authors: 
 - Aaron Beckerman
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2024-05-14 00:00:00 -07:00
+date: 2025-05-16 00:00:00 -07:00
 default_executable: 
 dependencies: []
 
@@ -30,7 +30,6 @@ extra_rdoc_files: []
 files: 
 - LICENSE.txt
 - README.txt
-- blackstart.gemspec
 - lib/blackstart.rb
 - test/blackstart_test.rb
 has_rdoc: true
@@ -69,5 +68,5 @@ rubygems_version: 1.6.2
 signing_key: 
 specification_version: 3
 summary: A small, subdued library for automated testing.
-test_files: 
-- test/blackstart_test.rb
+test_files: []
+

data/blackstart.gemspec

@@ -1,11 +0,0 @@
-Gem::Specification.new do |s|
-  s.name = "blackstart"
-  s.version = "0.2.0"
-  s.authors = ["Aaron Beckerman"]
-  s.summary = "A small, subdued library for automated testing."
-  s.licenses = ["MIT"]
-  s.required_ruby_version = ">= 1.8.7"
-  s.files = ["LICENSE.txt", "README.txt", "blackstart.gemspec",
-    "lib/blackstart.rb", "test/blackstart_test.rb"]
-  s.test_files = ["test/blackstart_test.rb"]
-end