The platform ships with its own tests (Workarea tests), which you can run from your application. When you run Workarea tests, any decorators you've written for those tests are applied. You can also write your own tests (application tests) that further extend the platform. ( See also Testing Concepts, Tests & Decorators. )
You run tests using one of many test runners. ( See Testing Concepts, Test Runners. )
It can be confusing which to use for a given situation, so this document provides instructions to:
Once you are familiar with these procedures, you may only need a reminder of specific details. In those situations you may want to refer to:
Run All Tests
Use the default Workarea test runner to run all tests: Workarea tests including your decorations of those tests, plus your own application tests.
You can also run this command with arguments. See Pass Arguments to Workarea Test Runners.
Run Workarea Tests
Additional Workarea test runners allow you to run tests by engine or run all plugin tests.
Run tests for a specific Workarea engine:
Alternatively, run tests for all installed Workarea plugins (all engines except Core, Admin, Storefront):
You can also run the above commands with arguments. See Pass Arguments to Workarea Test Runners.
Run Specific Workarea Tests
To run individual/specific Workarea test cases and tests, use the Rails test runner.
Pass the pathnames of the test files you'd like to run as arguments to the test runner.
bundle show to easily find the installation location of each Workarea engine.
For example, run the
UserTest test case from Workarea Core:
bin/rails test $(bundle show workarea-core)/test/models/workarea/user_test.rb
Use additional arguments to be more specific about which tests to run.
For example, use
-n to run specific tests within a test case:
bin/rails test $(bundle show workarea-core)/test/models/workarea/user_test.rb -n test_new_example
To see all available arguments, see Display Rails Test Runner Help.
Run Decorated Workarea Tests
You may want to run only the Workarea tests that you've decorated within your application.
Run all decorated tests:
( See also Pass Arguments to Workarea Test Runners. )
Run specific decorated tests using the general procedure for running specific Workarea tests.
However, the pathnames you pass as arguments must be the original
*.rb test files within the Workarea engine(s), not the
*.decorator files within your application.
You must locate the pathnames to the original test files and pass those to the test runner to run the tests.
Run Application Tests
Run your application tests like you would in any other Rails application (using the generic Rails test runner):
Be aware, the default Rails test runner doesn't run system tests. To run system tests, use:
To see all available arguments for these test runners, refer to Display Rails Test Runner Help.
Run Specific Application Tests
To run specific application tests, pass the pathnames of the test files as arguments to the Rails test runner:
bin/rails test <paths>
bin/rails test test/models/article_test.rb
Additional arguments are also available for more control over which tests are run and how they are run. See Display Rails Test Runner Help.
.decorator Test Files
Developers often make the mistake of passing
*.decorator file pathnames as test runner arguments.
Because decorators are extensions of existing classes, they are not complete test cases on their own and therefore can't be run as tests.
You must instead locate the pathnames of the original
*.rb test files and pass those pathnames as arguments.
List Test Runners
Once you are familiar with the commands from the sections above, you may simply need a refesher of which test runners exist.
List all available test runners (Rails and Workarea):
bin/rails -T test
Output will differ from app to app, depending on which plugins are installed and other variables, so run this command within your application to see which test runners are available.
Display Rails Test Runner Help
To see all the arguments accepted by the Rails test runner, view its inline help:
bin/rails test --help
The output lists all available arguments for the test runner, such as
-b to print backtraces,
-v for verbose output, and
-s to run a specific seed.
Pass Arguments to Workarea Test Runners
Workarea test runners accept the same arguments as the Rails test runners, but you must pass the arguments using the
TESTOPTS environment variable.
Refer to Display Rails Test Runner Help for all available arguments. Pass arguments using the following boilerplate:
TESTOPTS='<arguments>' bin/rails workarea:test:<runner>
For example, run all Core tests with verbose output using a specific seed:
TESTOPTS='-v -s 51477' bin/rails workarea:test:core
Or, run all decorated tests with backtraces enabled for failed tests:
TESTOPTS='-b' bin/rails workarea:test:decorated
Help Us Improve this Doc
Was this helpful? Open a GitHub issue to report a problem with this doc, suggest an improvement, or otherwise provide feedback. Thanks!