bitloops-gherkin

node.js package that automatically generates Gherkin tables in Cucumber .feature files from test data pulled from your Google Sheet! :heart_eyes: :star2: :tada:

Installation

:exclamation: Only yarn or npm is necessary! Don't do both!

If you install the global CLI, then you can fill your feature files by using the bitloops-gherkin command directly. If you only install it as a developer dependency add something like this in your scripts:

"encode": "./node_modules/.bin/env-cmd --silent -f .env ./node_modules/.bin/bitloops-gherkin encode -t",

In any case, it is advisable to install the developer dependency in your projects in order to import the decode function in your tests (see)

Yarn

To use as a developer dependency

yarn add -D bitloops-gherkin

Global package to run as a CLI

yarn global add bitloops-gherkin

npm

To use as a developer dependency

npm install --save-dev bitloops-gherkin

Global package to run as a CLI

npm install -g bitloops-gherkin

Usage

Requirements

• A Google Cloud Platform project (if you don't have one it is free to create one)
• Node.js (>=12)
• Google Drive account

Step 1 (Only need to do this once)

Enable the Google Sheets API and get an API credentials file from your Google Cloud Platform project.

See: Google Cloud Platform - Enable APIs Google Cloud Platform - Create API Key

Keep note of your API key.

You have two ways of using your API key. Either you include it in your command when you run the encode process (see) or just add it in a .env file as a parameter named BITLOOPS_GHERKIN_GOOGLE_SHEETS_API_KEY

Step 2

Create your Google Sheet that will contain your tests. Name the tabs after your tests as can be found in your steps file. See this example.

Make sure the Google Sheet has public read permissions. Make sure you start with a column named @status and add values active for the tests you want to be sent to your .feature file.

First of all, we create our Cucumber feature file as normal but instead of including the usual Example table, we add the Google sheet that contains our tests.

Feature file (e.g. testGoogleSheets.feature)

# https://docs.google.com/spreadsheets/d/1ILKwKeRaOEh7_uAVIyfDVqUPbEdCNIlAaOEFY-zdMzU/edit#gid=0
Feature: Test Google Sheets test generation using Bitloops

  Scenario Template: Valid arithmetic calculations
    Given I have the calculation string <calculationString>
    When I calculate the result
    Then I should see the result <output>

  Scenario Template: Invalid arithmetic calculations
    Given I have the calculation string <calculationString>
    Then I should receive an error <output>

Step 3

In your steps.ts file make sure you import bitloops-gherkin and wrap all test data with the decode or d functions.

import { defineFeature, loadFeature } from 'jest-cucumber';
import { decode, d } from 'bitloops-gherkin';

const feature = loadFeature('./__tests__/features/testGoogleSheets.feature');

defineFeature(feature, (test) => {
  let calculationString;
  let result;

  test('Valid arithmetic calculations', ({ given, when, then }) => {
    given(/^I have the calculation string (.*)$/, (arg0) => {
      calculationString = decode(arg0);
    });

    when('I calculate the result', () => {
      result = eval(calculationString).toString();
    });

    then(/^I should see the result (.*)$/, (arg1) => {
      expect(result).toEqual(decode(arg1));
    });
  });

  test('Invalid arithmetic calculations', ({ given, then }) => {
    given(/^I have the calculation string (.*)$/, (arg0) => {
      calculationString = d(arg0);
    });

    then(/^I should receive an error (.*)$/, (arg1) => {
      console.log(decoder(arg1));
      expect(() => eval(calculationString)).toThrow(d(arg1));
    });
  });
});

Step 4

Using an terminal command you can run the following:

./node_modules/.bin/env-cmd -f .env bitloops-gherkin encode -t ./__tests__/step-definitions/testGoogleSheets.steps.ts -k y0urAP1KeyHere

Using a .env file you can run the following:

./node_modules/.bin/env-cmd -f .env bitloops-gherkin encode -t ./__tests__/step-definitions/testGoogleSheets.steps.ts

That's it! :tada:

You should see your feature file automatically populated like below:

# https://docs.google.com/spreadsheets/d/1ILKwKeRaOEh7_uAVIyfDVqUPbEdCNIlAaOEFY-zdMzU/edit#gid=0
Feature: Test Google Sheets test generation using Bitloops

  Scenario Template: Valid arithmetic calculations
    Given I have the calculation string <calculationString>
    When I calculate the result
    Then I should see the result <output>

   # Examples: # @bitloops-auto-generated
       # | calculationString | output | @bitloops-auto-generated |
       # | 3 + 3 | 6 | @bitloops-auto-generated |
       # | 2 * 7 | 14 | @bitloops-auto-generated |
       # | 3 + 5 * 8 | 43 | @bitloops-auto-generated |
  
    Examples: # @bitloops-auto-generated
        | calculationString | output | @bitloops-auto-generated |
        | 51,32,43,32,51 | 54 | @bitloops-auto-generated |
        | 50,32,42,32,55 | 49,52 | @bitloops-auto-generated |
        | 51,32,43,32,53,32,42,32,56 | 52,51 | @bitloops-auto-generated |
  
  Scenario Template: Invalid arithmetic calculations
    Given I have the calculation string <calculationString>
    Then I should receive an error <output>

   # Examples: # @bitloops-auto-generated
       # | calculationString | output | @bitloops-auto-generated |
       # | 3 + hello | hello is not defined | @bitloops-auto-generated |
       # | 2 * world | world is not defined | @bitloops-auto-generated |
  
    Examples: # @bitloops-auto-generated
        | calculationString | output | @bitloops-auto-generated |
        | 51,32,43,32,104,101,108,108,111 | 104,101,108,108,111,32,105,115,32,110,111,116,32,100,101,102,105,110,101,100 | @bitloops-auto-generated |
        | 50,32,42,32,119,111,114,108,100 | 119,111,114,108,100,32,105,115,32,110,111,116,32,100,101,102,105,110,101,100 | @bitloops-auto-generated |
  

As you can see, your feature file now contains two sets of examples: one that is commented using # with your actual data for readability, and one with numbers that represent the Buffer encoded values of your data, allowing you to put any kind of data in your Gherkin tables.

PRO Tip: you can use structured JSON data to add any kind of test data in your tables.

Optional

To make it easier to run your command, while loading your .env file, you can create a script to place in your package.json file like the following:

"encode": "./node_modules/.bin/env-cmd --silent -f .env bitloops-gherkin encode -t",

Then to download and encode your tests into your feature file you can just run this:

yarn encode ./__tests__/step-definitions/testGoogleSheets.steps.ts

or

yarn encode ./__tests__/features/testGoogleSheets.feature

Finally, if you do not want to install the global CLI, you can add the following command to your package.json:

"encode": "./node_modules/.bin/env-cmd --silent -f .env ./node_modules/.bin/bitloops-gherkin encode -t",

Cool Sheet Features

Test Status

You can set a @status for your tests. You need to name the first column @status and set the test you want to run to active. You can set other statuses such as backlog for tests you have written to express requirements but that you don't want to go into production before you do the development that would cause your tests to fail.

Comments beside your tests

You can add as many columns that contain the @ignore decorator and these are ignored and never reach your .feature file.

API

decode | d

Decodes a string that contains comma-separated numbers that represent a Buffer Array and returns the string.

encode | e

Encodes a value from string to Buffer Array.

Commands

encode

Pull the data from the Google Sheet and adds the Gherkin table under each test. Its flags are -t for the test file and -k for the API key.

version

Shows the current version of the package and CLI.

copyright

Displays the copyright information.

Limitations

Currently, bitloops-gherkins supports API keys and public Google Sheet files. In the future, private sheets will also be supported.

Like what you see? Don't forget to star ⭐ our repo!