< pekel >

This is a runner for executing tests using the Cucumber-Js within Jest (version 25+).

npm i pekel

Cucumber Features Supported

• After
• AfterAll
• And
• Attachments
• Background
• Before
• BeforeAll
• But
• Comments
• Data Table
• DocString
• Given
• Rule
• Scenario
• Scenario Outline
• setDefaultTimeout
• setDefinitionFunctionWrapper
• setWorldConstructor
• Tags
• Then
• When

Setup

1. Install Peer Dependencies

   npm i cucumber -D

   npm i jest -D * if not already installed

2. Create A Feature File

   path/to/my/features/button.feature

   Feature: Button
   
   Given I go to home
   When I click the login button
   Then the login button is not visible

3. Write Your Hooks

   path/to/my/hooks.tsx

   import React from 'react';
   import ReactDOM from 'react-dom';
   import { AfterAll, BeforeAll } from 'cucumber';
   
   import App from './path/to/my/app';
   
   BeforeAll(function () {
       ReactDOM.render(
           <App/>,
           document.body
       )
   });
   
   AfterAll(function () {
       ReactDOM.unmountComponentAtNode(
           document.body
       )
   });

   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.

4. Write Your Steps

   path/to/my/steps.ts

   import { Given, When, Then } from 'cucumber';
   import expect from 'expect';
   
   Given(/I go to (.*)$/, function(link) {
       window.location.hash = `#/${link}`;
   });
   
   When(/I click the (\S+) button$/, function(name) {
       document.querySelector(`[data-test-id="${name}"]`).click();
   });
   
   Then(/the (\S+) button is (visible|not visible)$/, function(name, state) {
       expect(!!document.querySelector(`[data-test-id="${name}"]`))
           .toEqual(state === 'visible')
   });

5. Setup Your 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

   path/to/my/world.ts

   import { setWorldConstructor } from 'cucumber';
   
   setWorldConstructor(
       class MyWorld {
           pages = [];
       }
   );

6. Create/Modify your jest configuration:

   {
       "runner": "pekel",
   
       "setupFilesAfterEnv": [
           "path/to/my/hooks.ts",
           "path/to/my/steps.ts",
           "path/to/my/world.ts"
       ], 
   
       "testMatch": [
           "path/to/my/features/*.feature"
       ] 
   }

   If you have existing jest test cases that do not use Cucumber, create a separate configuration. You can use the Jest CLI to run against specific configurations:

   jest --config=path/to/my/config.json

   Property	Note
   restoreMocks	There is an open bug for jest to fix the implementation of this where it does not unset manual mocks that are defined using the __mock__ folders. However, if this is set true, pekel will perform a scan of all __mock__ folders and files and manually unmock them for you.
   runner	tells jest which runner to use while executing the tests
   setupFiles	A spot where you should add your window polyfills, eg. jest-canvas-mock. It can also be used as the spot where you render your application's entry component into the dom
   setupFilesAfterEnv	Add your steps, hooks, and world files here
   testMatch	Add a path pattern to your feature files here

Why?!

1. Maintaining two separate testing frameworks is a burden.

2. Cucumber is great, but the runner it provides is not nearly as well documented or as polished as Jest.

3. Other existing solutions failed to support:

   • Step Definitions that can be used in every feature file

   • Background

   • setWorldConstructor

   • setDefinitionFunctionWrapper

   • Scenario Outline

   • IDE Intellisense for feature files and steps