jest-runner-cucumber
Jest Test Runner for the Cucumber Framework
npm i jest-runner-cucumber
Table of Contents
Gherkin Features
Supported | Feature | Notes |
---|---|---|
✅ | And | |
✅ | Background | |
✅ | But | |
✅ | Comments | |
✅ | Data Table | |
✅ | DocString | if it finds the docString is JSON, it will parse it for you |
Rule | haven't seen examples of this; not sure if it's worth it | |
✅ | Scenario | |
✅ | Scenario Outline |
Cucumber Features
Supported | Feature | Notes |
---|---|---|
✅ | After | called after each scenario in a feature file |
✅ | AfterAll | called after the feature file is completed; unlike Cucumber, you will have access to "this" context here. |
Attachments | ||
✅ | Before | called before each scenario per feature file |
✅ | BeforeAll | called before the feature file is started; unlike Cucumber, you will have access to "this" context here. |
✅ | Given | |
setDefaultTimeout | use jest.setTimeout or set the timeout property in your jest config | |
✅ | setDefinitionFunctionWrapper | |
✅ | setWorldConstructor | |
Tags | need to identify a way to pass tags through jest | |
✅ | Then | |
✅ | When |
Additional Features
Supported | Feature | Notes |
---|---|---|
✅ | gherkin variables used to populate feature files |
Getting Started
Jest Config
If you have existing jest test cases that do not use Cucumber, you have two options:
-
create a separate configuration. You can use the Jest CLI to run against specific configurations:
jest --config=path/to/your/config.json
-
add a "projects" array to your existing configuration; moving any existing test configuration to inside of the projects array. Then, add your new jest configuration:
moduleFileExtensions:
"moduleFileExtensions":
* If you are not using typescript, remove "ts"
and "tsx"
runner:
"runner": "jest-runner-cucumber"
setupFiles (optional):
"setupFiles":
* Add your polyfills here. Here's an example
setupFilesAfterEnv:
"setupFilesAfterEnv":
testMatch:
"testMatch":
transform:
"transform":
* If you are not using typescript, remove "ts"
and "tsx"
restoreMocks (optional):
"restoreMocks": true
If you are planning on writing integration tests, I highly recommend that you set this to true. There is an open bug for jest to fix an issue where it does not unset manual mocks that are defined using __mock__ folders. However, if this is set true, jest-runner-cucumber will perform a scan of all __mock__ folders and files and manually unmock them for you.
Cucumber
Feature
path/to/your/features/button.feature
Feature: Button Given I go to homeWhen I click the login buttonThen the login button is not visible
Hooks
path/to/your/hooks.tsx
;;; ; BeforeAll; AfterAll;
You can choose to use the hooks to render/unmount your component before/after each feature file like above, or you can add a path to your application entry point to your jest configuration's setupFiles property. The latter is more performant.
Steps
path/to/your/steps.ts
;; Given/I go to $/, ; When/I click the button$/, ; Then/the button is $/, ;
World
setWorldConstuctor allows you to set the context of "this" for your steps/hooks definitions. This can be helpful when you want to maintain state between steps/hooks or want your steps/hooks to have access to some predefined data. The values are accessible within all Hooks, and Steps by using this
path/to/your/world.ts
; setWorldConstructor ;
Example Output
Below is an example output from running tests against the example
PASS test/features/scenarioOutline.feature (97 MB heap size) Feature: Sign Up - Submitting With Extra Emails ✓ Given the firstName text input value is Dayne (37 ms) ✓ And the lastName text input value is Mentier (11 ms) ✓ And the email text input value is dayne.mentier@gmail.com (13 ms) ✓ And the password text input value is itsASecretShh... (9 ms) ✓ And the extraEmails checkbox input is not checked (2 ms) ✓ When the submit button is clicked (89 ms) ✓ Then POST http://127.0.0.1:8080/api/sign-up is called with the request body: (3 ms) ✓ And the successAlert is visible (2 ms) ✓ And the showExtraEmailsAlert is not visible (2 ms) Feature: Sign Up - Submitting Without Extra Emails ✓ Given the firstName text input value is Dayne (12 ms) ✓ And the lastName text input value is Mentier (11 ms) ✓ And the email text input value is dayne.mentier@gmail.com (8 ms) ✓ And the password text input value is itsASecretShh... (10 ms) ✓ And the extraEmails checkbox input is checked (9 ms) ✓ When the submit button is clicked (45 ms) ✓ Then POST http://127.0.0.1:8080/api/sign-up is called with the request body: (1 ms) ✓ And the successAlert is visible (1 ms) ✓ And the showExtraEmailsAlert is visible (1 ms) PASS test/features/scenario.feature (93 MB heap size) Feature: Sign Up - Without Extra Emails ✓ Given the firstName text input value is Dayne (11 ms) ✓ And the lastName text input value is Mentier (12 ms) ✓ And the email text input value is dayne.mentier@gmail.com (11 ms) ✓ And the password text input value is itsASecretShh... (14 ms) ✓ When the submit button is clicked (66 ms) ✓ Then POST http://127.0.0.1:8080/api/sign-up is called with the request body: (5 ms) ✓ And the successAlert is visible (2 ms) ✓ And the showExtraEmailsAlert is not visible (2 ms) Feature: Sign Up - With Extra Emails ✓ Given the firstName text input value is Dayne (14 ms) ✓ And the lastName text input value is Mentier (12 ms) ✓ And the email text input value is dayne.mentier@gmail.com (12 ms) ✓ And the password text input value is itsASecretShh... (9 ms) ✓ And the extraEmails checkbox input is checked (9 ms) ✓ When the submit button is clicked (49 ms) ✓ Then POST http://127.0.0.1:8080/api/sign-up is called with the request body: (1 ms) ✓ And the successAlert is visible (2 ms) ✓ And the showExtraEmailsAlert is visible (1 ms) PASS test/features/scenarioBackground.feature (85 MB heap size) Feature: Sign Up - Without Extra Emails ✓ Given the firstName text input value is Dayne (14 ms) ✓ And the lastName text input value is Mentier (13 ms) ✓ And the email text input value is dayne.mentier@gmail.com (15 ms) ✓ And the password text input value is itsASecretShh... (22 ms) ✓ When the submit button is clicked (66 ms) ✓ Then POST http://127.0.0.1:8080/api/sign-up is called with the request body: (3 ms) ✓ And the successAlert is visible (4 ms) ✓ And the showExtraEmailsAlert is not visible (2 ms) Feature: Sign Up - With Extra Emails ✓ Given the firstName text input value is Dayne (10 ms) ✓ And the lastName text input value is Mentier (8 ms) ✓ And the email text input value is dayne.mentier@gmail.com (10 ms) ✓ And the password text input value is itsASecretShh... (8 ms) ✓ And the extraEmails checkbox input is checked (7 ms) ✓ When the submit button is clicked (46 ms) ✓ Then POST http://127.0.0.1:8080/api/sign-up is called with the request body: ✓ And the successAlert is visible (2 ms) ✓ And the showExtraEmailsAlert is visible (1 ms) Test Suites: 3 passed, 3 totalTests: 52 passed, 52 totalSnapshots: 0 totalTime: 7.603 sRan all test suites.
Gherkin Variables
This provides the ability to define variables in your feature files, and hold the values in a separate file. A few things to note for this functionality is:
- the file must contain the same name as the feature file you're looking to populate
- all variables start with a "$"; eg, in the feature file, the variable would be defined as $email, while the vars file would contain email
- you can further split up your vars files by using the CUCUMBER_ENV variable. Using that, your files would look like this:
featureFileName.CUCUMBER_ENV.vars.{js,ts,json}
For an example, see the example scenarioOutline feature file, and the accompanying variable file
MockXHR
One of the hardest thing I've found when using jest as a runner for integration tests is figuring out how to properly spy on api calls and mock the requests. I've included a helper class called MockXHR that simplifies the process. Below is an example of how to set it up in your World and Hooks
;;;; ; setWorldConstructor After; AfterAll; BeforeAll;
MockXHR provides a spy that is called whenever a request goes out, this can be use your steps like this:
Then/^ is called with the :$/, ;
Scenario: Without Extra Emails When the submit button is clicked Then POST /api/sign-up is called with the request body: """ { "firstName": "Dayne", "lastName": "Mentier", "email": "dayne.mentier@gmail.com", "password": "itsASecretShh...", "extraEmails": false } """
Internally, it uses xhr-mock. Unlike nock which causes memory leak issues because it is mutating native node modules, xhr-mock does not. I've also found that if your http lib is axios, you can also run into memory leak issues if you do not mock the follow-redirects. That lib has the same issue as nock; it mutates the native http and https modules, which causes leaking. If you are using axios make sure you add the following mock to one of your entry files:
jest.mock'follow-redirects',;