A Gherkin based DSL for testing HTTP APIs via Cucumber.JS.
- Write RESTful/HTTP API tests in plain English.
- Integrates with Open API specs.
- Easily extend with Cucumber.JS.
Given I am anonymous When I send a 'GET' request to '{base}/pets' And I add the query string parameters: | sort | desc | | filter | mammal | Then I should receive a response with the status 200 And I should receive a response within 1000ms And the response body json path at "$.[1].name" should equal "Rover"
See the step definition reference for a complete
list of all the available Given
, When
and Then
steps.
Contents
Install
npm i --save-dev @harver/bat
Get started
1. Install Cucumber.JS:
npm install --save-dev cucumber
features/support/setup.js
with the following code:
2. Create the file const setWorldConstructor After AfterAll Before BeforeAll Given When Then } = ;const registerHooks World registerSteps = ; ; // Allow Bat to hook into your Cucumber dependencty:;;
3. Write feature files and scenarios
features/some-scenario.feature
:
Scenario: Testing Gets When I send a 'GET' request to '{base}/pets' And I add the query string parameters: | sort | desc | | filter | red | Then I should receive a response with the status 200 And I should receive a response within 1000ms And the response body json path at "$.[1].name" should equal "Rover"
See the Steps Reference for documentation on all available steps.
Cucumber.JS CLI to run your specs
4. Use the./node_modules/.bin/cucumber-js
Tips
Use a Postman compatible environment file to define variables:
ENV_FILE=env/uat.json cucumber-js
The env file will look like this:
You may then reference this variables, in your steps, like so:
When I send a 'GET' request to '{base}/pets'
Integrate with an Open API 3 specification:
API_SPEC_FILE=test/openapi.yaml cucumber-js
An Open API spec can be used in conjunction with provided steps, such as extracting example request bodies or validating responses against their schemas.
Step short forms
Steps are written in a readable English form, but this can seem quite verbose. Therefore most steps have alternative short form. For example:
Scenario: Testing short forms When GET '/pets' And qs: | sort | desc | | filter | mammal | Then receive status 200 And within 1000ms And json path at "$.[1].name" should equal "Rover"
Adding a latency buffer
If you are using the I should receive a response within {int}ms
step on a network connection you expect to be unusually slow,
you can add pad the time of all these steps using the LATENCY_BUFFER
environment variable:
LATENCY_BUFFER=1000 cucumber-js
This example allows an extra second for all requests to complete.
Extending
Under the hood, Bat uses SuperAgent for making HTTP requests. You can get a new SuperAgent agent without requiring SuperAgent directly as a dependency by calling this.newAgent()
within a custom
step definition:
const agent = this;
Bat also maintains a cache of agents that persists across Cucumber scenarios. This
means that if each scenario uses a Given
step to set up some authorization, an HTTP session or Bearer token can be reused without needing to re-login every time.
The code example below (taken from the tests), demonstrates a custom Given
step
for logging in and maintaining a client session:
const setWorldConstructor After AfterAll Before BeforeAll Given When Then = ;const registerHooks World registerSteps = ; ;;; // a custom login step;
See the Cucumber.JS documentation for more information on writing step definitions.
Reference
Steps reference for support writing feature files.
World API for support writing custom step definitions.