{"id":15270317,"url":"https://github.com/bitloops/bitloops-gherkin-ts","last_synced_at":"2025-10-16T12:58:07.805Z","repository":{"id":58509852,"uuid":"532218294","full_name":"bitloops/bitloops-gherkin-ts","owner":"bitloops","description":"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 ^^^","archived":false,"fork":false,"pushed_at":"2022-10-12T21:04:31.000Z","size":313,"stargazers_count":5,"open_issues_count":1,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-12T07:18:24.291Z","etag":null,"topics":["bdd","cucumber","cucumber-js","gherkin","google-sheets","testing","typescript"],"latest_commit_sha":null,"homepage":"","language":"Gherkin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bitloops.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-09-03T09:48:11.000Z","updated_at":"2023-07-25T15:01:14.000Z","dependencies_parsed_at":"2023-01-19T23:35:02.396Z","dependency_job_id":null,"html_url":"https://github.com/bitloops/bitloops-gherkin-ts","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitloops%2Fbitloops-gherkin-ts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitloops%2Fbitloops-gherkin-ts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitloops%2Fbitloops-gherkin-ts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitloops%2Fbitloops-gherkin-ts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bitloops","download_url":"https://codeload.github.com/bitloops/bitloops-gherkin-ts/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248530602,"owners_count":21119601,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bdd","cucumber","cucumber-js","gherkin","google-sheets","testing","typescript"],"created_at":"2024-09-30T07:08:13.161Z","updated_at":"2025-10-16T12:58:07.730Z","avatar_url":"https://github.com/bitloops.png","language":"Gherkin","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Bitloops][bitloops-logo]\n\n# bitloops-gherkin\n\n[![GitHub Actions CI][ci-badge]][ci-url]\n[![npm version][npmimg]][npm]\n[![Known Vulnerabilities][snyk-image]][snyk-url]\n[![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)\n\nnode.js package that automatically generates Gherkin tables in Cucumber .feature files from test data pulled from your Google Sheet! :heart_eyes: :star2: :tada:\n\n![Demo](https://storage.googleapis.com/bitloops-github-assets/bitloops-gherkin-v0.2.3.gif)\n\n## Installation\n\n\u003e :exclamation: Only yarn or npm is necessary! Don't do both!\n\nIf 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:\n\n```json\n\"encode\": \"./node_modules/.bin/env-cmd --silent -f .env ./node_modules/.bin/bitloops-gherkin encode -t\",\n```\n\nIn 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))\n\n### Yarn\n\nTo use as a developer dependency\n\n```bash\nyarn add -D bitloops-gherkin\n```\n\nGlobal package to run as a CLI\n\n```bash\nyarn global add bitloops-gherkin\n```\n\n### npm\n\nTo use as a developer dependency\n\n```bash\nnpm install --save-dev bitloops-gherkin\n```\n\nGlobal package to run as a CLI\n\n```bash\nnpm install -g bitloops-gherkin\n```\n\n## Usage\n\n### Requirements\n\n- A Google Cloud Platform project (if you don't have one it is free to create one)\n- Node.js (\u003e=12)\n- Google Drive account\n\n### Step 1 (Only need to do this once)\n\nEnable the Google Sheets API and get an API credentials file from your Google Cloud Platform project.\n\nSee:\n[Google Cloud Platform - Enable APIs](https://developers.google.com/workspace/guides/enable-apis)\n[Google Cloud Platform - Create API Key](https://developers.google.com/workspace/guides/create-credentials#api-key)\n\nKeep note of your API key.\n\nYou 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**\n\n### Step 2\n\nCreate 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).\n\u003e Make sure the Google Sheet has public read permissions.\n\u003e 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.\n\nFirst 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.\n\n**Feature file** (*e.g. testGoogleSheets.feature*)\n\n```feature\n# https://docs.google.com/spreadsheets/d/1ILKwKeRaOEh7_uAVIyfDVqUPbEdCNIlAaOEFY-zdMzU/edit#gid=0\nFeature: Test Google Sheets test generation using Bitloops\n\n  Scenario Template: Valid arithmetic calculations\n    Given I have the calculation string \u003ccalculationString\u003e\n    When I calculate the result\n    Then I should see the result \u003coutput\u003e\n\n  Scenario Template: Invalid arithmetic calculations\n    Given I have the calculation string \u003ccalculationString\u003e\n    Then I should receive an error \u003coutput\u003e\n```\n\n### Step 3\n\nIn your steps.ts file make sure you import **bitloops-gherkin** and wrap all test data with the **decode** or **d** functions.\n\n```typescript\nimport { defineFeature, loadFeature } from 'jest-cucumber';\nimport { decode, d } from 'bitloops-gherkin';\n\nconst feature = loadFeature('./__tests__/features/testGoogleSheets.feature');\n\ndefineFeature(feature, (test) =\u003e {\n  let calculationString;\n  let result;\n\n  test('Valid arithmetic calculations', ({ given, when, then }) =\u003e {\n    given(/^I have the calculation string (.*)$/, (arg0) =\u003e {\n      calculationString = decode(arg0);\n    });\n\n    when('I calculate the result', () =\u003e {\n      result = eval(calculationString).toString();\n    });\n\n    then(/^I should see the result (.*)$/, (arg1) =\u003e {\n      expect(result).toEqual(decode(arg1));\n    });\n  });\n\n  test('Invalid arithmetic calculations', ({ given, then }) =\u003e {\n    given(/^I have the calculation string (.*)$/, (arg0) =\u003e {\n      calculationString = d(arg0);\n    });\n\n    then(/^I should receive an error (.*)$/, (arg1) =\u003e {\n      console.log(decoder(arg1));\n      expect(() =\u003e eval(calculationString)).toThrow(d(arg1));\n    });\n  });\n});\n```\n\n### Step 4\n\nUsing an terminal command you can run the following:\n\n\u003e./node_modules/.bin/env-cmd -f .env bitloops-gherkin encode -t ./\\_\\_tests\\_\\_/step-definitions/testGoogleSheets.steps.ts -k y0urAP1KeyHere\n\nUsing a .env file you can run the following:\n\n\u003e ./node_modules/.bin/env-cmd -f .env bitloops-gherkin encode -t ./\\_\\_tests\\_\\_/step-definitions/testGoogleSheets.steps.ts\n\n### That's it! :tada:\n\nYou should see your feature file automatically populated like below:\n\n```feature\n# https://docs.google.com/spreadsheets/d/1ILKwKeRaOEh7_uAVIyfDVqUPbEdCNIlAaOEFY-zdMzU/edit#gid=0\nFeature: Test Google Sheets test generation using Bitloops\n\n  Scenario Template: Valid arithmetic calculations\n    Given I have the calculation string \u003ccalculationString\u003e\n    When I calculate the result\n    Then I should see the result \u003coutput\u003e\n\n   # Examples: # @bitloops-auto-generated\n       # | calculationString | output | @bitloops-auto-generated |\n       # | 3 + 3 | 6 | @bitloops-auto-generated |\n       # | 2 * 7 | 14 | @bitloops-auto-generated |\n       # | 3 + 5 * 8 | 43 | @bitloops-auto-generated |\n  \n    Examples: # @bitloops-auto-generated\n        | calculationString | output | @bitloops-auto-generated |\n        | 51,32,43,32,51 | 54 | @bitloops-auto-generated |\n        | 50,32,42,32,55 | 49,52 | @bitloops-auto-generated |\n        | 51,32,43,32,53,32,42,32,56 | 52,51 | @bitloops-auto-generated |\n  \n  Scenario Template: Invalid arithmetic calculations\n    Given I have the calculation string \u003ccalculationString\u003e\n    Then I should receive an error \u003coutput\u003e\n\n   # Examples: # @bitloops-auto-generated\n       # | calculationString | output | @bitloops-auto-generated |\n       # | 3 + hello | hello is not defined | @bitloops-auto-generated |\n       # | 2 * world | world is not defined | @bitloops-auto-generated |\n  \n    Examples: # @bitloops-auto-generated\n        | calculationString | output | @bitloops-auto-generated |\n        | 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 |\n        | 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 |\n  \n```\n\nAs 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.\n\n\u003e PRO Tip: you can use structured JSON data to add any kind of test data in your tables.\n\n### Optional\n\nTo 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:\n\n```json\n\"encode\": \"./node_modules/.bin/env-cmd --silent -f .env bitloops-gherkin encode -t\",\n```\n\nThen to download and encode your tests into your **feature** file you can just run this:\n\n```bash\nyarn encode ./__tests__/step-definitions/testGoogleSheets.steps.ts\n```\nor\n```bash\nyarn encode ./__tests__/features/testGoogleSheets.feature\n```\n\nFinally, if you do not want to install the global CLI, you can add the following command to your **package.json**:\n\n```json\n\"encode\": \"./node_modules/.bin/env-cmd --silent -f .env ./node_modules/.bin/bitloops-gherkin encode -t\",\n```\n\n## Cool Sheet Features\n\n### Test Status\n\nYou 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.\n\n### Comments beside your tests\n\nYou can add as many columns that contain the *@ignore* decorator and these are ignored and never reach your *.feature* file.\n\n## API\n\n### decode | d\n\nDecodes a string that contains comma-separated numbers that represent a Buffer Array and returns the string.\n\n### encode | e\n\nEncodes a value from string to Buffer Array.\n\n## Commands\n\n### encode\n\nPull 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.\n\n### version\n\nShows the current version of the package and CLI.\n\n### copyright\n\nDisplays the copyright information.\n\n## Limitations\n\nCurrently, bitloops-gherkins supports API keys and public Google Sheet files. In the future, private sheets will also be supported.\n\n# Like what you see? Don't forget to star ⭐ our repo!\n\n[bitloops-logo]: https://storage.googleapis.com/wwwbitloopscom/bitloops-logo_320x80.png\n[ci-badge]: https://github.com/bitloops/bitloops-gherkin-ts/workflows/CI/badge.svg\n[ci-url]: https://github.com/bitloops/bitloops-gherkin-ts/actions/workflows/main.yml\n[snyk-image]: https://snyk.io/test/github/bitloops/bitloops-gherkin-ts/badge.svg\n[snyk-url]: https://snyk.io/test/github/bitloops/bitloops-gherkin-ts\n[npmimg]: https://img.shields.io/npm/v/bitloops-gherkin.svg\n[npm]: https://www.npmjs.org/package/bitloops-gherkin\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitloops%2Fbitloops-gherkin-ts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbitloops%2Fbitloops-gherkin-ts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitloops%2Fbitloops-gherkin-ts/lists"}