README.md in assert-2.15.0 vs README.md in assert-2.15.1

- old
+ new

@@ -1,9 +1,7 @@ # The Assert Testing Framework -Test::Unit style testing framework, just better than Test::Unit. - ## Usage ```ruby # in test/my_tests.rb @@ -32,34 +30,41 @@ ## 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). -* **Backwards compatible**: (assuming a few minor tweaks) with Test::Unit test suites ## What Assert is not -* **Rspec** -* **Unit/Functional/Integration/etc**: Assert is agnostic - you define whatever kinds of tests you like (one or more of the above) 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. +* **RSpec/spec-anything**: define tests using assertion statements +* **Unit/Functional/Integration/etc**: Assert is agnostic - you define whatever kinds of tests you like (one or more of the above) 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 a Test::Unit style testing framework. This means you can write tests in Assert the same way you would with test-unit. +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. -In addition, Assert adds some helpers and syntax sugar to enhance the way tests are written. Most are taken from ideas in [Shoulda](https://github.com/thoughtbot/shoulda) and [Leftright](https://github.com/jordi/leftright/). Assert uses class-based contexts so if you want to nest your contexts, use inheritance. +### Features -**Note**: Assert is tested using itself. The tests are a pretty good place to look for examples and usage patterns. +* `assert` [executable](https://github.com/redding/assert#cli) 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 +* full backtrace for errors +* optionally pretty print objects in failure descriptions +* [stubbing API](https://github.com/redding/assert#stub) +* [factory API](https://github.com/redding/assert#factory) +* `skip` to skip tests +* `Ctrl+c` stops tests and prints failures ## Defining tests -TODO +**Note**: Assert is tested using itself. The tests are a good place to look for examples and usage patterns. -## Factory - -TODO - ## Stub ```ruby myclass = Class.new do def mymeth; 'meth'; end @@ -88,34 +93,82 @@ Assert.stub(myobj, :myval){ 'stub-meth' } # => StubError: arity mismatch Assert.stub(myobj, :myval).with(123){ |val| val.to_s } myobj.myval # => StubError: arity mismatch -myobj.mymeth(123) +myobj.myval(123) # => '123' -myobj.mymeth(456) - # => StubError: `mymeth(456)` not stubbed. +myobj.myval(456) + # => StubError: `myval(456)` not stubbed. Assert.unstub(myobj, :mymeth) +Assert.unstub(myobj, :myval) myobj.mymeth # => 'meth' myobj.myval(123) # => 123 myobj.myval(456) # => 456 ``` -Assert comes with a simple 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: +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 added to `Object` +* no methods are added to `Object` to support stubbing * stubs are auto-unstubbed on test teardown +## Factory + +```ruby +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: + +```ruby +module Factory + extend Assert::Factory + + def self.data + { Factory.string => Factory.string } + end +end +``` + ## CLI ```sh $ assert --help ``` @@ -137,39 +190,39 @@ * `$ 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 (hint: use tab-completion) and Assert will find any test files and run the tests in them. +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 ```ruby 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, CLI, ENV. +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, CLI, and ENV 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 CLI, and ENV 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. -### CLI settings +### ENV settings -Assert accepts options from its CLI. Use these options to specify runtime settings. CLI settings can be overridden by 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. -### ENV settings +### CLI settings -Assert uses ENV vars to drive certain settings. Use these vars to specify absolute runtime settings. ENV settings are always applied last and cannot be overridden. +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`](/lib/assert/runner.rb) to run tests. You can extend this default runner or use your own runner implementation. Specify it in your user/local settings: @@ -201,32 +254,50 @@ end ``` ### Test Order -The default runner object runs tests in random order. To run tests in a consistant order, specify a custom runner seed: +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: ```ruby Assert.configure do |config| config.runner_seed 1234 end ``` +Using an ENV var: + +```sh +$ ASSERT_RUNNER_SEED=1234 assert +``` + Using the CLI: ```sh $ assert [-s|--runner-seed] 1234 ``` -Using an ENV var: +### 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 run just a single test, pass its file path and line number: + ```sh -$ ASSERT_RUNNER_SEED=1234 assert +$ assert [-t|--single-test] ./path/for/tests.rb:123 ``` +**Note**: by default Assert outputs, in the details of each non-passing result, the cmd to re-run the result's test: + +``` +FAIL: should pass +./test/unit/test_tests.rb:124 +assert -t ./test/unit/test_tests.rb:123 +``` + ### Verbose Output By default, Assert shows terse runtime test result information. It provides a setting to turn on/off more verbose information: In user/local settings file: @@ -454,22 +525,22 @@ ``` However, the view handler you use is itself configurable. Define you own view handler class and specify it in your user/local settings: ```ruby -class MyCustomView < Assert::View::Base +class MyCustomView < Assert::View # define your view here... end Assert.configure do |config| config.view MyCustomView.new end ``` ### Anatomy of a View -A view class handles the logic and templating of test result output. A view class should inherit from `Assert::View::Base`. This defines default callback handlers for the test runner and gives access to a bunch of common helpers for reading test result data. +A view class handles the logic and templating of test result output. A view class should inherit from `Assert::View`. This defines default callback handlers for the test runner and gives access to a bunch of common helpers for reading test result data. Each view should implement the callback handler methods to output information at different points during the running of a test suite. Callbacks have access to any view methods and should output information using `puts` and `prints`. See the `DefaultView` template for a usage example. Available callbacks from the runner, and when they are called: @@ -532,11 +603,11 @@ Tests produce results as they are executed. Every `assert` statement produces a result. Some results, like `Error` and `Skip`, will halt execution. `Pass` and `Ignore` results do not halt execution. `Fail` results, by default, halt execution but there is an option to have them not halt execution. Therefore, tests can have many results of varying types. ### View -A `View` object is responsible for rendering test result output. Assert provides a `Assert::View::Base` object to provide common helpers and default runner callback handlers for building views. Assert also provides an `Assert::DefaultView` that it renders its output with. See the "Viewing Test Results" section below for more details. +A `View` object is responsible for rendering test result output. Assert provides a `Assert::View` object to provide common helpers and default runner callback handlers for building views. Assert also provides an `Assert::DefaultView` that it renders its output with. See the "Viewing Test Results" section below for more details. ### Macro Macros are procs that define sets of test code and make it available for easy reuse. Macros work nicely with the 'should' and 'test' context methods. @@ -558,6 +629,6 @@ 4. Push to the branch (`git push origin my-new-feature`) 5. Create new Pull Request One note: please respect that Assert itself is intended to be the flexible, base-level, framework-type logic that should change little if at all. Pull requests for niche functionality or personal testing philosphy stuff will likely not be accepted. -If you wish to extend Assert for your niche purpose/desire/philosophy, please do so in it's own gem (preferrably named `assert-<whatever>`) that uses Assert as a dependency. When you do, tell us about it and we'll add it to this README with a short description. +If you wish to extend Assert for your niche purpose/desire/philosophy, please do so in it's own gem (preferrably named `assert-<whatever>`) that uses Assert as a dependency.