Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/bitloops/bitloops-gherkin-ts

bitloops-gherkin is a node.js package that automatically generates Gherkin tables in Cucumber .feature files from test data pulled from your Google Sheet! Liking what you are seeing? Don't forget to star ⭐ us ^^^
https://github.com/bitloops/bitloops-gherkin-ts

bdd cucumber cucumber-js gherkin google-sheets testing typescript

Last synced: 2 months ago
JSON representation

Host: GitHub
URL: https://github.com/bitloops/bitloops-gherkin-ts
Owner: bitloops
License: gpl-3.0
Created: 2022-09-03T09:48:11.000Z (over 2 years ago)
Default Branch: main
Last Pushed: 2022-10-12T21:04:31.000Z (about 2 years ago)
Last Synced: 2024-10-01T07:07:53.139Z (3 months ago)
Topics: bdd, cucumber, cucumber-js, gherkin, google-sheets, testing, typescript
Language: Gherkin
Homepage:
Size: 306 KB
Stars: 5
Watchers: 3
Forks: 1
Open Issues: 1
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md

Awesome Lists containing this project

README

        ![Bitloops][bitloops-logo]

# bitloops-gherkin

[![GitHub Actions CI][ci-badge]][ci-url]

[![npm version][npmimg]][npm]

[![Known Vulnerabilities][snyk-image]][snyk-url]

[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fbitloops%2Fbitloops-gherkin-ts.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2Fbitloops%2Fbitloops-gherkin-ts?ref=badge_shield)

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

![Demo](https://storage.googleapis.com/bitloops-github-assets/bitloops-gherkin-v0.2.3.gif)

## 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:

```json

"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](#step-3))

### Yarn

To use as a developer dependency

```bash

yarn add -D bitloops-gherkin

```

Global package to run as a CLI

```bash

yarn global add bitloops-gherkin

```

### npm

To use as a developer dependency

```bash

npm install --save-dev bitloops-gherkin

```

Global package to run as a CLI

```bash

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](https://developers.google.com/workspace/guides/enable-apis)

[Google Cloud Platform - Create API Key](https://developers.google.com/workspace/guides/create-credentials#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](#optional)) 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](https://docs.google.com/spreadsheets/d/1ILKwKeRaOEh7_uAVIyfDVqUPbEdCNIlAaOEFY-zdMzU/edit#gid=0).

> 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*)

```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 

    When I calculate the result

    Then I should see the result 

  Scenario Template: Invalid arithmetic calculations

    Given I have the calculation string 

    Then I should receive an error 

```

### Step 3

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

```typescript

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:

```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 

    When I calculate the result

    Then I should see the result 

   # 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 

    Then I should receive an error 

   # 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:

```json

"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:

```bash

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

```

or

```bash

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**:

```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!

[bitloops-logo]: https://storage.googleapis.com/wwwbitloopscom/bitloops-logo_320x80.png

[ci-badge]: https://github.com/bitloops/bitloops-gherkin-ts/workflows/CI/badge.svg

[ci-url]: https://github.com/bitloops/bitloops-gherkin-ts/actions/workflows/main.yml

[snyk-image]: https://snyk.io/test/github/bitloops/bitloops-gherkin-ts/badge.svg

[snyk-url]: https://snyk.io/test/github/bitloops/bitloops-gherkin-ts

[npmimg]: https://img.shields.io/npm/v/bitloops-gherkin.svg

[npm]: https://www.npmjs.org/package/bitloops-gherkin