BDD & Integration Testing (Cucumber)
Relevant source files
The following files were used as context for generating this wiki page:
Behavior-Driven Development (BDD) and integration testing in Actionmap are primarily driven by Cucumber. This system allows developers to define application requirements in plain language features and verify them through automated browser-based interactions. The testing infrastructure leverages Capybara and Webrat to simulate user behavior, ensuring that the integration between Rails controllers, models, and views functions correctly.
The testing environment is configured to use a dedicated test database, with DatabaseCleaner managing state between scenarios to ensure test isolation. The project utilizes a combination of generic web steps for standard interactions and domain-specific steps for representative-related workflows.
Sources: features/support/env.rb:25-30, features/step_definitions/web_steps.rb:1-15
Test Infrastructure and Configuration
The Cucumber environment is initialized via env.rb, which integrates the Rails application with the Cucumber-Rails gem. It configures SimpleCov for code coverage, excluding the lib directory from analysis.
Execution Profiles
Cucumber execution is managed through cucumber.yml, which defines several profiles for running tests under different conditions.
| Profile | Description | Options |
|---|---|---|
default | Standard test run excluding work-in-progress tags. | --strict --tags 'not @wip' features |
wip | Runs scenarios specifically tagged with @wip. | --tags @wip:3 --wip features |
rerun | Re-runs only the scenarios that failed in the previous execution. | --format rerun --out rerun.txt |
Sources: config/cucumber.yml:1-8, features/support/env.rb:11-20
Database Management
The system uses DatabaseCleaner to maintain a clean state. By default, it uses the :transaction strategy for speed, but switches to :truncation for scenarios involving JavaScript execution to handle threading requirements.
Sources: features/support/env.rb:49-75
Step Definitions and Helper Modules
Actionmap utilizes a modular approach to step definitions, separating generic browser interactions from specific business logic.
Web Steps and Scoping
Generic interactions (visiting pages, clicking buttons, filling forms) are defined in web_steps.rb. These steps often utilize WithinHelpers to scope actions to specific DOM elements.
- Navigation:
Given I am on [page_name] - Interactions:
When I press "[button]",When I follow "[link]" - Form Input:
When I fill in "[field]" with "[value]" - Assertions:
Then I should see "[text]"
Sources: features/step_definitions/web_steps.rb:36-85
Domain-Specific Steps (Representatives)
Specialized steps for the representative and news modules are defined in representative_steps.rb. These steps interact with the Representative model to resolve names to specific database IDs before navigating.
Support Infrastructure
The testing framework relies on mapping layers to translate human-readable names into technical identifiers.
Path Mapping
The NavigationHelpers module in paths.rb converts descriptive page names used in features into actual URL paths. If a specific mapping is not found, it attempts to dynamically generate a path helper name.
Sources: features/support/paths.rb:15-35
Selector Mapping
The HtmlSelectorsHelpers module in selectors.rb maps descriptive names to CSS or XPath selectors. This abstraction allows features to remain readable even when targeting complex UI components.
| Descriptive Name | CSS/XPath Mapping |
|---|---|
| "the page" | html > body |
| Quoted string | Returns the string as a direct selector |
Sources: features/support/selectors.rb:12-35
Summary
The BDD system in Actionmap provides a robust integration testing layer. By combining web_steps.rb for generic browser control with representative_steps.rb for domain-specific logic, the project ensures that critical paths—such as searching for representatives and viewing local news—remain functional. The use of DatabaseCleaner and environment-specific configurations in cucumber.yml ensures that the test suite is reliable and reproducible across different development environments.