{"id":24060832,"url":"https://github.com/harver-engineering/bat","last_synced_at":"2025-04-23T07:53:25.108Z","repository":{"id":35073473,"uuid":"165429257","full_name":"harver-engineering/bat","owner":"harver-engineering","description":"Gherkin based DSL for testing HTTP APIs via Cucumber.JS","archived":false,"fork":false,"pushed_at":"2023-01-23T23:57:41.000Z","size":658,"stargazers_count":34,"open_issues_count":19,"forks_count":10,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-29T22:51:16.458Z","etag":null,"topics":["api","bdd","bdd-framework","cucumber","cucumber-js","gherkin","gherkin-dsl","rest","testing-tools"],"latest_commit_sha":null,"homepage":"https://harver.com/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/harver-engineering.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-01-12T19:49:49.000Z","updated_at":"2024-04-29T07:20:50.000Z","dependencies_parsed_at":"2023-02-13T05:10:15.549Z","dependency_job_id":null,"html_url":"https://github.com/harver-engineering/bat","commit_stats":null,"previous_names":["harver-bv/bat"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harver-engineering%2Fbat","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harver-engineering%2Fbat/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harver-engineering%2Fbat/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harver-engineering%2Fbat/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/harver-engineering","download_url":"https://codeload.github.com/harver-engineering/bat/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250395189,"owners_count":21423375,"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":["api","bdd","bdd-framework","cucumber","cucumber-js","gherkin","gherkin-dsl","rest","testing-tools"],"created_at":"2025-01-09T07:15:08.152Z","updated_at":"2025-04-23T07:53:25.083Z","avatar_url":"https://github.com/harver-engineering.png","language":"JavaScript","readme":"Bat 🦇 - Behavioral API Tester \u0026middot; [![Build Status](https://travis-ci.org/harver-engineering/bat.svg?branch=master)](https://travis-ci.org/harver-engineering/bat) ![npm (scoped)](https://img.shields.io/npm/v/@harver/bat) ![GitHub](https://img.shields.io/github/license/harver-engineering/bat)\n==============================\n\nA [Gherkin](https://docs.cucumber.io/gherkin/) based DSL for testing HTTP APIs via [Cucumber.JS](https://github.com/cucumber/cucumber-js).\n\n* Write RESTful/HTTP API tests in plain English.\n* Integrates with Open API specs.\n* Easily extend with [Cucumber.JS](https://github.com/cucumber/cucumber-js).\n\n```gherkin\n    Given I am anonymous\n    When I send a 'GET' request to '{base}/pets'\n    And I add the query string parameters:\n        | sort   | desc   |\n        | filter | mammal |\n    Then I should receive a response with the status 200\n    And I should receive a response within 1000ms\n    And the response body json path at \"$.[1].name\" should equal \"Rover\"\n```\n\nSee the [step definition reference](./docs/step-reference.md) for a complete\nlist of all the available `Given`, `When` and `Then` steps.\n\n## Contents\n\n * [Install](#install)\n * [Get started](#get-started)\n * [Tips](#tips)\n * [Extending](#extending)\n * [Reference](#reference)\n\n## Install\n\n```\nnpm i --save-dev @harver/bat\n```\n\n## Get started\n\n### 1. Install Cucumber.JS:\n\n`npm install --save-dev cucumber`\n\n### 2. Create the file `features/support/setup.js` with the following code:\n\n```javascript\nconst {\n    setWorldConstructor,\n    After, AfterAll, Before, BeforeAll,\n    Given, When, Then\n} = require('cucumber');\nconst { registerHooks, World, registerSteps } = require('@harver/bat');\n\nsetWorldConstructor(World);\n\n// Allow Bat to hook into your Cucumber dependencty:\nregisterHooks({ Before, BeforeAll, After, AfterAll });\nregisterSteps({ Given, Then, When });\n```\n\n### 3. Write feature files and scenarios\n\n`features/some-scenario.feature`:\n\n```gherkin\nScenario: Testing Gets\n    When I send a 'GET' request to '{base}/pets'\n    And I add the query string parameters:\n        | sort   | desc |\n        | filter | red  |\n    Then I should receive a response with the status 200\n    And I should receive a response within 1000ms\n    And the response body json path at \"$.[1].name\" should equal \"Rover\"\n```\n\nSee the [Steps Reference](./docs/step-reference.md) for documentation on all available steps.\n\n### 4. Use the [Cucumber.JS CLI](https://github.com/cucumber/cucumber-js/blob/master/docs/cli.md) to run your specs\n\n`./node_modules/.bin/cucumber-js`\n\n## Tips\n\n### Use a Postman compatible environment file to define variables:\n\n`ENV_FILE=env/uat.json cucumber-js`\n\nThe env file will look like this:\n\n```json\n{\n    \"values\": [\n        {\n            \"key\": \"base\",\n            \"value\": \"http://localhost:3000\"\n        }\n    ]\n}\n```\n\nYou may then reference this variables, in your steps, like so:\n\n```gherkin\nWhen I send a 'GET' request to '{base}/pets'\n```\n\n### Integrate with an Open API 3 specification:\n\n`API_SPEC_FILE=test/openapi.yaml cucumber-js`\n\nAn Open API spec can be used in conjunction with provided steps, such as\nextracting example request bodies or validating responses against their\nschemas.\n\n### Step short forms\n\nSteps are written in a readable English form, but this can seem quite verbose. Therefore most steps have alternative short form. For example:\n\n```gherkin\nScenario: Testing short forms\n    When GET '/pets'\n    And qs:\n        | sort   | desc    |\n        | filter | mammal  |\n    Then receive status 200\n    And within 1000ms\n    And json path at \"$.[1].name\" should equal \"Rover\"\n```\n\n### Adding a latency buffer\n\nIf you are using the `I should receive a response within {int}ms` step on a network connection you expect to be unusually slow,\nyou can add pad the time of all these steps using the `LATENCY_BUFFER` environment variable:\n\n`LATENCY_BUFFER=1000 cucumber-js`\n\nThis example allows an extra second for all requests to complete.\n\n## Extending\n\nUnder the hood, Bat uses [SuperAgent](https://visionmedia.github.io/superagent/) for making HTTP requests. You can get a new SuperAgent agent without requiring SuperAgent directly as a dependency by calling `this.newAgent()` within a custom\nstep definition:\n\n```javascript\nconst agent = this.newAgent();\n```\n\nBat also maintains a cache of agents that persists across Cucumber scenarios. This\nmeans that if each scenario uses a `Given` step to set up some authorization, an HTTP session or Bearer token can be reused without needing to re-login every time.\n\nThe code example below (taken from the tests), demonstrates a custom `Given` step\nfor logging in and maintaining a client session:\n\n```javascript\nconst { setWorldConstructor, After, AfterAll, Before, BeforeAll, Given, When, Then } = require('cucumber');\nconst { registerHooks, World, registerSteps } = require('@harver/bat');\n\nsetWorldConstructor(World);\nregisterHooks({ After, AfterAll, Before, BeforeAll });\nregisterSteps({ Given, Then, When });\n\n// a custom login step\nGiven('I am logged in as a {string}', async function(role) {\n    // does an agent for this role already exist?\n    const roleAgent = this.getAgentByRole(role);\n    if (roleAgent) {\n        this.setAgentByRole(role, roleAgent);\n        return;\n    }\n\n    // construct and send a login request\n    const agent = this.newAgent();\n    const req = agent.post(this.replaceVars('{base}/my-login'));\n\n    await req.send({\n        // this gets predefined credentials for this role from the `env/dev.json` file\n        username: this.replaceVars(`{${role}_user}`),\n    });\n\n    // this also sets `this.currentAgent` so this agent will be used\n    // for creating the next request.\n    this.setAgentByRole(role, agent);\n});\n```\n\nSee the [Cucumber.JS](https://github.com/cucumber/cucumber-js/blob/master/docs/support_files/step_definitions.md) documentation for more information on writing step definitions.\n\n\n## Reference\n\n[Steps reference](./docs/step-reference.md) for support writing feature files.\n\n[World API](./docs/world-api.md) for support writing custom step definitions.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fharver-engineering%2Fbat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fharver-engineering%2Fbat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fharver-engineering%2Fbat/lists"}