An open-source, command-line testing tool based on Cucumber.js, built to support and streamline Behavior-Driven Development (BDD).
npm install @specify-bdd/specify
!Node LTS
!NPM Unpacked Size
!GitHub License
!GitHub Actions Workflow Status
Behavior-Driven Development (BDD) doesn't have to be a slog. Specify makes it easy to turn requirements into
actionable tests, streamlining your development process with clear acceptance criteria, rapid iteration, and confident
deployments.
Built on Cucumber.js and enhanced with numerous convenience features and QOL
improvements informed by over a decade of experience in automated testing, Specify was built using the same BDD
principles it exists to support. We use Specify to test itself end-to-end (E2E) in addition to our unit and
integration tests. Whether you want to embrace BDD fully or just experiment with automated testing, Specify can help.
1. Quick Start
2. Installation
* Installing Plugins
* Prerequisites
3. Configuration
* Configuring Cucumber
* Configuring Plugins
4. Defining Behavior
5. Running Tests
* Runtime Options
6. Extending Specify
* Cucumber Support Code
* Step Definitions
* Hooks
* Custom Plugins
7. Get Help
---
Create a behavior spec file:
``gherkin`
Feature: Gherkin feature file that should pass
Scenario: Scenario that should pass
When this step passes
Run the behavior spec as a test:
`bash
$ npx specify path/to/behavior.feature
.....
1 scenario (1 passed)
1 step (1 passed)
0m00.697s (executing steps: 0m00.009s)
`
Specify can be downloaded with NPM. It's recommended that you save it as a dev dependency for your project:
`bash`
npm i -D @specify-bdd/specify
Alternatively, you can install the package globally:
`bash`
npm i -g @specify-bdd/specify
Specify ships with only a few demo step definitions, but many more are available for download as plugins. Install these
additional packages in the same manner (dev dependency or global) as the main Specify package.
Official Specify plugin packages:
* CLI (@specify-bdd/plugin-cli): Command-line interface
support
Plugins must be added to the Specify configuration before they can be used. See
Configuring Plugins for more info.
* Node.js v22.x (LTS Jod) or newer
Specify's default settings can be overridden by creating a file in the current working directory named
specify.config.json. (This should be the directory that the user will be executing specify commands from.) This
JSON object should conform to structure of a
CoreConfig.
It is possible to change the default settings that Specify's instance of Cucumber.js uses by modifying the cucumber
property of . In the following example, the output format of Cucumber is being set to JSON.
`json`
{
"cucumber": {
"format": [ "json" ],
"import": [ "path/to/cucumber/support/code" ]
}
}
The plugins property of CoreConfig is an array of strings which identify Specify plugin packages by either their
scoped package name (the same one used to install the package) or a file system path for the directory which contains
the plugin's package.json file. Only plugins included in this list are known to and usable by Specify.
`json`
{
"plugins": [ "@specify-bdd/plugin-cli" ]
}
Behavior specifications are written in Gherkin, a domain-specific language
which is easy for non-technical colleagues to read and understand, but structured enough to be machine-parsable.
Behavior is described in feature documents (text files with a .feature extension) covering one discrete unit of
user-facing functionality apiece. Each feature is elaborated upon with scenarios, short narrative descriptions of
how the feature ought to behave under various conditions. These scenarios are made up of a series of steps which
detail the exact sequence of user actions and system reactions that ought to take place.
Gherkin uses a small number of keywords (e.g. "Feature", "Scenario", "Given", "When", and "Then") to give the document
structure and semantic meaning. The rest of the language used to describe the desired behavior is freeform and up to
the feature's author. However, using consistent and repeatable language to describe common actions can save a lot of
effort when it comes time to parse the Gherkin and take action. See
Step Definitions for more.
With the behavior specs and any necessary supporting code in place, you can execute tests with the following command:
`bash`
specify test [options] [paths...]
The paths... argument should be the path or paths of the behavior specs you want to execute. If you put those specs./features
in the directory (relative to the location you are running the command from), they will be detected
automatically and no paths argument is required.
The following options governing the runtime behavior of Specify are available:
| Option | Description |
| -------------------------| ---------------------------------------------------------------------------------- |
| -h, --help | Display this help screen. |
| -p, --parallel
| --rerun | Rerun the failed tests from the last test run. |
| --rerun-file
| -r, --retry
| --retry-tag
| -t, --tags
| -w, --watch | Watch for changes and re-run tests. |
Specify's functionality is built to be modular and extensible by design because we knew there are too many corner cases
and unique requirements in BDD and automated testing for us to ever cover the spread ourselves. While Specify aims to
provide for the most common use cases with our official plugins, we encourage others to build custom integrations to
meet their own needs and to publish compatible plugin packages when that need is shared by others.
The simplest way to extend Specify functionality is with Cucumber support code additions. New step definitions, hooks,
parameter types, etc. can be created within your project hierarchy and included by Cucumber using the cucumber.import
config setting. See Configuring Cucumber for more details.
#### Step Definitions
A step definition is a piece of Cucumber support
code which matches a predefined pattern (represented as a
Cucumber expression or regexp) to a callback function. The
pattern can include parameters (or capturing groups for regexp) which will extract matched values and pass them on to
the callback function. Specify's plugins (see Installing Plugins) provide prebuilt step
definitions to help accelerate test automation, but you can also write your own step definitions to cover behaviors
unique to your use cases or combine multiple basic actions into one step.
#### Hooks
Cucumber hooks allow you to execute
custom code before and after steps, scenarios, and the entire test suite. Setup/teardown, cleanup, and logging
operations commonly use this feature to ensure their own timely execution.
While Cucumber support code can be stored in your project repo and imported via configuration, it may be useful to
package certain utilities for portability, so that they are easier to share between different projects or even publish
independently. To this end, Specify is built on a plugin architecture which you can use to make your packages easy to
share and use.
To create a plugin, ensure that your utility's package.json file defines a main module which has, as its defaultCoreConfig
export, a object. This object will be merged with those of other plugins as well as Specify's base configcucumber
and any user override JSON file which may exist. If your package includes Cucumber support code which you want your
users to auto-import, simply configure the property of the CoreConfig object to include the paths of thoseimport` sub-property as shown in the Configuring Cucumber section.
support files in its
Additional plugin capabilities beyond adding Cucumber support code will be added in the future.
Having trouble with Specify? We're here to help.