Testing Concepts

Workarea includes a test suite and tools for extending Workarea with your own tests. This document explains the following concepts related to testing with the Workarea platform:

Tests & Decorators

Workarea applications are Rails applications and therefore inherit the toolchain and patterns for testing Rails apps. Refer to that document for Rails testing fundamentals, such as Minitest, test cases, and assertions.

However, a new Workarea application includes a broad feature set by default and therefore includes tests for those features. You can run the platform's own tests (referred to here as Workarea tests, to differentiate them from application tests) from your application. ( See Run Tests. )

You can also extend the platform's test suite by writing decorators for existing tests and writing your own tests (referred to here as application tests to differentiate them from Workarea tests). ( See Decorate & Write Tests. )

When you extend Workarea with your own customizations and functionality, you should extend the test suite as well. As a general rule, you should prefer writing new test cases over decorating existing test cases. New tests are easier to reason about and run. ( See Run Tests. )

However, in some situtations decorating an existing test case is necessary. Decorate a Workarea test case when your platform extensions have caused an existing test to fail. In this case, decorate the test case and fix or skip the failing tests. ( See Decorate & Write Tests. ) Furthermore, use a test case decorator to fix existing tests only. If you need to write new tests, write them in their own (new) test case within your application.

Test Runners

Test runners are command line applications used to run tests (Workarea tests and application tests).

Rails provides its own test runners, and Workarea adds test runners that make it more convenient to run Workarea tests. Knowing which test runner to use with which arguments can be confusing, so refer to the recipes in Run Tests.

Test Helper

Every Rails test file begins by requiring the application test helper, a file located at <application_root>/test/test_helper.rb. This file boots the application into an appropriate test environment and bootstraps it for testing. This includes loading Rails' test help, <railties>/lib/rails/test_help.rb, and Workarea's test help, <workarea-testing>/lib/workarea/test_help.rb.

You'll see this file required in the boilerplate for writing your own tests.

Test Case Types

Workarea defines its own test case types, and all Workarea test cases inherit from one of those types.

When writing your own tests, choose the appropriate test case type. Refer to the following table for brief descriptions, and click through to the sources to see the full implementation of each type.

Test Case Type Description
Workarea::TestCase Generic Workarea test case based on ActiveSupport::TestCase that supports test decorators and other Workarea extensions
Workarea::IntegrationTest Workarea integration test case based on ActionDispatch::IntegrationTest that provides decorator support, Workarea extensions, and additional instance methods, such as set_current_user
Workarea::SystemTest Workarea system test case based on ActionDispatch::SystemTestCase that provides Headless Chrome setup and extensions to Capybara, such as wait_for_xhr
Workarea::ViewTest Workarea view test case based on ActionView::TestCase
Workarea::MailerTest Workarea mailer test case based on ActionMailer::TestCase
Workarea::GeneratorTest Workarea generator test case based on Rails::Generators::TestCase

Test Case Mixins

Many of the test case types described above include behavior that is defined in shared modules, referred to here as test case mixins. You can mix these modules into any test case that doesn't already include them.

Therefore, when writing your own tests, after choosing the appropriate test case type, mix in any additional modules required for your specific test case. Refer to the following table.

You can also extend these mixins to change their behavior as needed for your application. ( See Extend Test Case Mixins. )

Test Case Mixin Description
Workarea::TestCase::Workers Provides setup and teardown to enable workers to run (inline)
Workarea::TestCase::SearchIndexing Provides setup for use of Elasticsearch indexes
Workarea::TestCase::Mail Provides setup and teardown enabling sending of mail
Workarea::Admin::IntegrationTest Ensures a default Admin user
Workarea::Storefront::IntegrationTest Provides test "macros" such as complete_checkout
Workarea::Storefront::SystemTest Provides test "macros" such as add_product_to_cart
Workarea::BreakpointHelpers Provides test "macros" such as resize_window_to

Test Factories

Test factories are modules whose methods provide shortcuts for creating model instances. Within your tests, you can call factory methods (e.g. create_product) to create model instances with default data appropriate for testing.

View the Base factories in <workarea-testing>/lib/workarea/testing/factories/.

Many test case types include factories by default, and you can include factories in any test cases that don't by including Workarea::Factories within the test case definition. All other factories "register" themselves with this "master" module, so that only this module must be included to provide access to all factory methods.

Within your application, you can configure the default data for each factory, and you can add your own factories for your own custom functionality. ( See Configure & Add Test Factories. )

Headless Chrome

Since Workarea 3.3.0, system tests use an instance of headless Chrome, driven by Selenium. When running the tests locally, Workarea will use your standard Chrome installation.

To support all environments, you can configure the arguments passed to Chrome and Selenium. ( See Configure Headless Chrome. )

Now on GitHub