The Assert Testing Framework

Usage

# in test/my_tests.rb

require "assert"

class MyTests < Assert::Context
  test "something" do
    assert_that(1).equals(1)
  end
end

$ assert test/my_tests.rb
Loaded suite (1 test)
Running tests in random order, seeded with "56382"
.

1 result: pass

(0.000128 seconds, 7812.500000 tests/s, 7812.500000 results/s)

What Assert is

• Framework: you define tests and the context they run in - Assert runs them. Everything is pure ruby so use any 3rd party testing tools you like. Create 3rd party tools that extend Assert behavior.
• First Class: everything is a first class object and can be extended to your liking (and should be)
• MVC: tests and how they are defined (M) and executed (C) are distinct from how you view the test results (V).

What Assert is not

• RSpec/spec-anything: define tests using assertion statements.
• Unit/Functional/Integration/etc: Assert is agnostic - you define whatever kinds of tests you like and Assert runs them in context.
• Mock/Spec/BDD/etc: Assert is the framework and there are a variety of 3rd party tools to do such things. Feel free to use whatever you like.

Description

Assert is an assertion-style testing framework, meaning you use assertion statements to define your tests and create results. Assert uses class-based contexts so if you want to nest your contexts, use inheritance.

Features

• assert executable for running tests
• run tests by tab completing test file paths
• run only test files that have been modified
• random order test execution
• class-based contexts
• multiple before/setup & after/teardown blocks
• around blocks
• let value declarations
• full backtrace for errors
• optionally pretty print objects in failure descriptions
• stubbing API
• factory API
• skip to skip tests
• Ctrl+c stops tests and prints failures

Defining tests

Note: Assert is tested using itself. The tests are a good place to look for examples and usage patterns.

Stub

Assert comes with a stubbing API - all it does is replace method calls. In general it tries to be friendly and complain if stubbing doesn't match up with the object/method being stubbed:

• each stub takes a block that is called in place of the method
• complains if you stub a method that the object doesn't respond to
• complains if you stub with an arity mismatch
• no methods are added to Object to support stubbing
• stubs are auto-unstubbed on test teardown

Note: Assert's stubbing logic has been extracted into a separate gem: MuchStub. However, the main Assert.{stub|unstub|stub_send|stub_tap|etc} api is still available (it just proxies to MuchStub now).

myclass = Class.new do
  def my_method
    "my_method"
  end

  def my_value(value)
    value
  end
end
my_object = myclass.new

my_object.my_method
  # => "my_method"
my_object.my_value(123)
  # => 123
my_object.my_value(456)
  # => 456

Assert.stub(my_object, :my_method)
my_object.my_method
  # => StubError: `my_method` not stubbed.
Assert.stub(my_object, :my_method){ "stub-meth" }
my_object.my_method
  # => "stub-meth"
my_object.my_method(123)
  # => StubError: arity mismatch
Assert.stub(my_object, :my_method).with(123){ "stub-meth" }
  # => StubError: arity mismatch

# Call the original method after it has been stubbed.
Assert.stub_send(my_object, :my_method)
  # => "my_method"

Assert.stub(my_object, :my_value){ "stub-meth" }
  # => StubError: arity mismatch
Assert.stub(my_object, :my_value).with(123){ |val| val.to_s }
my_object.my_value
  # => StubError: arity mismatch
my_object.my_value(123)
  # => "123"
my_object.my_value(456)
  # => StubError: `my_value(456)` not stubbed.

# Call the original method after it has been stubbed.
Assert.stub_send(my_object, :my_value, 123)
  # => 123
Assert.stub_send(my_object, :my_value, 456)
  # => 456

# Stub a method while preserving its behavior and return value.
my_value_called_with = nil
Assert.stub_tap(my_object, :my_value) { |value, *args|
  my_value_called_with = args
  Assert.stub(value, :to_s) { "FIREWORKS!" }
}
value = my_object.my_value(123)
  # => 123
my_value_called_with
  # => [123]
value.to_s
  # =>"FIREWORKS!"

# Unstub individual stubs
Assert.unstub(my_object, :my_method)
Assert.unstub(my_object, :my_value)

# OR blanket unstub all stubs
Assert.unstub!

my_object.my_method
  # => "my_method"
my_object.my_value(123)
  # => 123
value = my_object.my_value(456)
  # => 456
value.to_s
  # => "456"

Factory

require "assert/factory"

Assert::Factory.integer    #=> 15742
Assert::Factory.integer(3) #=> 2
Assert::Factory.float      #=> 87.2716908041922
Assert::Factory.float(3)   #=> 2.5466638138805

Assert::Factory.date       #=> #<Date: 4915123/2,0,2299161>
Assert::Factory.time       #=> Wed Sep 07 10:37:22 -0500 2016
Assert::Factory.datetime   #=> #<DateTime: 302518290593/43200,0,2299161>

Assert::Factory.string     #=> "boxsrbazeq"
Assert::Factory.string(3)  #=> "rja"
Assert::Factory.text       #=> "khcwyizmymajfzzxlfwz"
Assert::Factory.text(3)    #=> "qcy"
Assert::Factory.slug       #=> "licia"
Assert::Factory.slug(3)    #=> "luu"
Assert::Factory.hex        #=> "48797adb33"
Assert::Factory.hex(3)     #=> "2fe"
Assert::Factory.url        #=> "/cdqz/hqeq/zbsl"
Assert::Factory.email      #=> "vyojvtxght@gmrin.com"

Assert::Factory.file_name  #=> "kagahm.ybb"
Assert::Factory.path       #=> "jbzf/omyk/vbha"
Assert::Factory.dir_path   #=> "fxai/lwnq/urqu"
Assert::Factory.file_path  #=> "bcno/pzxg/gois/mpvlfo.wdr"

Assert::Factory.binary     #=> "\000\000\003S"
Assert::Factory.boolean    #=> false

Assert::Factory is an API for generating randomized data. The randomization is tied to the runner seed so re-running tests with the same seed should produce the same random values.

You can also extend on your own factory class:

module Factory
  extend Assert::Factory

  def self.data
    { Factory.string => Factory.string }
  end
end

Note: Assert's factory logic has been extracted into a separate gem: MuchFactory. However, the main api above is still available (it just delegates to MuchFactory now).

CLI

$ assert --help

Assert ships with a CLI for running tests. Test files must end in _tests.rb (or _test.rb). The CLI globs any given file path(s), requires any test files, and runs the tests in them.

As an example, say your test folder has a file structure like so:

- test
|  - basic_tests.rb
|  - helper.rb
|  - complex_tests.rb
|  - complex
|  |  - fast_tests.rb
|  |  - slow_tests.rb

• $ assert - runs all tests ("./test" is used if no paths are given)
• $ assert test/basic - run all tests in basic_tests.rb
• $ assert test/complex/fast_tests.rb - runs all tests in fast_tests.rb
• $ assert test/basic test/comp - runs all tests in basic_tests.rb, complex_tests.rb, fast_tests.rb and slow_tests.rb

All you need to do is pass some sort of existing file path (use tab-completion!) and Assert will find any test files and run the tests in them.

Configuring Assert

Assert.configure do |config|
  # set your config options here
end

Assert uses a config pattern for specifying settings. Using this pattern, you can configure settings, extensions, custom views, etc. Settings can be configured in 4 different scopes and are applied in this order: User, Local, ENV, CLI.

User settings

Assert will look for and require the file $HOME/.assert/init.rb. Use this file to specify user settings. User settings can be overridden by Local, ENV, and CLI settings.

Local settings

Assert will look for and require the file ./.assert.rb. Use this file to specify project settings. Local settings can be overridden by ENV, and CLI settings.

To specify a custom local settings file path, use the ASSERT_LOCALFILE env var.

ENV settings

Assert uses ENV vars to drive certain settings. Use these vars to specify specific environment settings. ENV settings can be overridden by CLI settings.

CLI settings

Assert accepts options from its CLI. Use these options to specify absolute runtime settings. CLI settings are always applied last and cannot be overridden.

Running Tests

Assert uses its Assert::Runner to run tests. You can extend this default runner or use your own runner implementation. Specify it in your user/local settings:

require "my_awesome_runner_class"

Assert.configure do |config|
  config.runner MyAwesomeRunnerClass.new
end

Test Dir

By default Assert expects tests in the test dir. The is where it looks for the helper file and is the default path used when running $ assert. To override this dir, do so in your user/local settings file:

Assert.configure do |config|
  config.test_dir "testing"
end

Test Helper File

By default Assert will look for a file named helper.rb in the test_dir and require it (if found) just before running the tests. To override the helper file name, do so in your user/local settings file:

Assert.configure do |config|
  config.test_helper "some_helpers.rb"
end

Test Order

The default runner object runs tests in random order. To run tests in a consistant order, pass a custom runner seed:

In user/local settings file:

Assert.configure do |config|
  config.runner_seed 1234
end

Using an ENV var:

$ ASSERT_RUNNER_SEED=1234 assert

Using the CLI:

$ assert [-s|--runner-seed] 1234

Run a single test

You can choose to run just a single test so that you can focus on making it pass without the overhead/noise from the output of the other tests in the file.

It is recommended that you only use this setting from the CLI. To ru