blackstart 0.1.0

data/LICENSE.txt

@@ -0,0 +1,19 @@
+Copyright (c) 2024 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
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.txt

@@ -0,0 +1,152 @@
+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 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.
+
+Here's an example of a test program that uses Blackstart:
+
+  require "blackstart"
+
+  exit Blackstart.run Blackstart.add { |adder|
+    adder.call do
+      unless "Hello, World!" == ["He", "", "o, Wor", "d!"].join("l")
+        raise "join did not work as expected"
+      end
+    end
+
+    adder.call do
+      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.
+
+The library provides little beyond this, but it's easy to do relatively
+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.
+
+
+- Defining helpers
+
+You may want all your tests to be able 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:
+
+  class Blackstart::Context
+    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 }
+      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.
+
+
+- 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:
+
+  class Blackstart::Context
+    def instance_exec(*)
+      puts "doing setup"
+      @variable = "example"
+      super
+    ensure
+      puts "doing teardown"
+    end
+  end
+
+
+- Building a test collection in stages
+
+You can build your collection of test objects in stages and run it at the end.
+For example:
+
+  require "blackstart"
+
+  TEST_OBJECTS = []
+
+  Blackstart.add TEST_OBJECTS do |adder|
+    adder.call do
+      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
+      unless "sample" == "simple".gsub(/i/, "a")
+        raise "gsub did not work as expected"
+      end
+    end
+  end
+
+  exit Blackstart.run TEST_OBJECTS
+
+This makes it straightforward to define your tests in multiple files that you
+load in your test program.
+
+
+- Running 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.
+
+
+- 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 produces when used as expected, 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.
+
+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.
+
+
+- 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.

data/blackstart.gemspec

@@ -0,0 +1,11 @@
+Gem::Specification.new do |s|
+  s.name = "blackstart"
+  s.version = "0.1.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

data/lib/blackstart.rb

@@ -0,0 +1,92 @@
+##
+# This module provides facilities for defining and running automated tests.
+
+module Blackstart
+
+  ##
+  # Calls 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.
+
+  def self.vet &prc
+    prc.call
+    nil
+  rescue ::StandardError
+    # Like IO#puts, separate lines with a line feed character rather than $\.
+    ["#{$!.class}: #{$!.message}"].concat($!.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.
+
+  class Context
+  end
+
+  ##
+  # Runs the 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.
+  #
+  # 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) }
+        success = false
+        ostream.puts "FAILED TEST:", tst.to_s, "...ERROR:", err_desc.to_s, ""
+      end
+    end
+    success
+  end
+
+end

data/test/blackstart_test.rb

@@ -0,0 +1,404 @@
+# Sections that create local variables are in class definitions so that later
+# sections cannot accidentally reference those local variables.
+
+require "blackstart"
+
+# Blackstart should be a module.
+fail "" unless Module.equal? Blackstart.class
+
+# Blackstart should say it responds to vet, add, and run.
+fail "" unless Blackstart.respond_to? :vet
+fail "" unless Blackstart.respond_to? :add
+fail "" unless Blackstart.respond_to? :run
+
+# Test Blackstart.vet:
+
+# Blackstart.vet should raise an exception if any non-block arguments are sent.
+begin
+  Blackstart.vet nil
+rescue ArgumentError
+else
+  fail ""
+end
+begin
+  Blackstart.vet(nil) {}
+rescue ArgumentError
+else
+  fail ""
+end
+
+# If sending call with no arguments to the block raises an error,
+# Blackstart.vet should return a new descriptive string.
+class ::Object
+  fail "" unless /\ANoMethodError: / =~ Blackstart.vet
+
+  e_class = Class.new StandardError
+  def e_class.to_s
+    "FakeError".freeze
+  end
+
+  e_nil = e_class.new "a".freeze
+  def e_nil.backtrace
+    nil
+  end
+  fail "" unless "FakeError: a" == Blackstart.vet { ::Kernel.raise e_nil }
+
+  e_empty = e_class.new "b".freeze
+  def e_empty.backtrace
+    [].freeze
+  end
+  fail "" unless "FakeError: b" == Blackstart.vet { ::Kernel.raise e_empty }
+
+  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
+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.
+class ::Object
+  sink = []
+  begin
+    Blackstart.add(sink) { |adder| adder.call("invalid") {} }
+  rescue ArgumentError
+  else
+    fail ""
+  end
+  begin
+    Blackstart.add(sink) { |adder| adder.call "invalid" }
+  rescue ArgumentError
+  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.
+class ::Object
+  e = StandardError.new
+  begin
+    Blackstart.add { ::Kernel.raise e }
+  rescue
+    fail "" unless e.equal? $!
+  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
+
+# 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::Context:
+
+# 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::Context.new should raise an exception if any non-block arguments
+# are sent.
+begin
+  Blackstart::Context.new nil
+rescue ArgumentError
+else
+  fail ""
+end
+
+# Test Blackstart.run:
+
+# Blackstart.run should send appropriate messages to the output stream and
+# 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.
+    original_stdout = $stdout
+    spy_stdout = $stdout.clone
+    spy_stdout.instance_variable_set :@_test_calls, stdout_calls = []
+    def spy_stdout.puts *args
+      @_test_calls << args
+      nil
+    end
+    $stdout = spy_stdout
+
+    # No tests.
+    source = [].freeze
+    fail "" unless true.equal? Blackstart.run(source, Object.new)
+    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)
+    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
+    def e_class.to_s
+      "FakeError"
+    end
+    fail_prc1 = proc { ::Kernel.raise e_class, "fake message 1" }
+    def fail_prc1.to_s
+      "to_s 1"
+    end
+    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" }
+    end
+    def fail_prc2.to_s
+      "to_s 2"
+    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 ""
+    end
+    fail "" unless 0 == stdout_calls.length
+
+    # Output stream that conforms to the expected interface.
+    spy_ostream = Object.new
+    spy_ostream.instance_variable_set :@_test_calls, calls = []
+    def spy_ostream.puts *args
+      @_test_calls << args
+      nil
+    end
+    fail "" unless false.equal? Blackstart.run(source, spy_ostream)
+    fail "" unless 0 == stdout_calls.length
+    fail "" unless 2 == calls.length
+    fail "" unless 5 == calls[0].length
+    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 "" == calls[0][4]
+    fail "" unless 5 == calls[1].length
+    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 "" == calls[1][4]
+    spy_ostream = calls = nil
+
+    # Default output stream.
+    stdout_calls.clear
+    fail "" unless false.equal? Blackstart.run(source)
+    fail "" unless 2 == stdout_calls.length
+    fail "" unless 5 == stdout_calls[0].length
+    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 "" == stdout_calls[0][4]
+    fail "" unless 5 == stdout_calls[1].length
+    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 "" == stdout_calls[1][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 }]
+    begin
+      Blackstart.run source, spy_stdout
+    rescue non_standard_error
+    else
+      fail ""
+    end
+    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.)
+    begin
+      Blackstart.run nil, spy_stdout
+    rescue NoMethodError
+    else
+      fail ""
+    end
+    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
+    # StandardError exceptions raised by tests.)
+    source = [nil]
+    begin
+      Blackstart.run source, spy_stdout
+    rescue ArgumentError
+    else
+      fail ""
+    end
+    source = [0]
+    begin
+      Blackstart.run source, spy_stdout
+    rescue TypeError
+    else
+      fail ""
+    end
+    bad_to_proc = Object.new
+    def bad_to_proc.to_proc
+      nil
+    end
+    source = [bad_to_proc]
+    begin
+      Blackstart.run source, spy_stdout
+    rescue TypeError
+    else
+      fail ""
+    end
+    fail "" unless 0 == stdout_calls.length
+  ensure
+    $stdout = original_stdout
+  end
+end
+
+# Blackstart.run should call each test proc with no arguments.
+class ::Object
+  args = nil
+  tst = proc do |*a|
+    args = a
+  end
+  Blackstart.run [tst], nil
+  fail "" unless [] == args
+end
+
+# Blackstart.run should call each test proc in the context of a unique instance
+# of Blackstart::Context.
+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
+end
+
+# Blackstart.run should raise an exception if too few or too many non-block
+# arguments are sent.
+begin
+  Blackstart.run
+rescue ArgumentError
+else
+  fail ""
+end
+begin
+  Blackstart.run [], nil, "invalid"
+rescue ArgumentError
+else
+  fail ""
+end
+
+# If this message doesn't get written, there was a problem.
+puts "Test finished: #{__FILE__}"

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification 
+name: blackstart
+version: !ruby/object:Gem::Version 
+  hash: 27
+  prerelease: 
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Aaron Beckerman
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2024-03-19 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: 
+email: 
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- LICENSE.txt
+- README.txt
+- blackstart.gemspec
+- lib/blackstart.rb
+- test/blackstart_test.rb
+has_rdoc: true
+homepage: 
+licenses: 
+- MIT
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 57
+      segments: 
+      - 1
+      - 8
+      - 7
+      version: 1.8.7
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.6.2
+signing_key: 
+specification_version: 3
+summary: A small, subdued library for automated testing.
+test_files: 
+- test/blackstart_test.rb