{"id":18728568,"url":"https://github.com/nightwatchjs/nightwatch-plugin-apitesting","last_synced_at":"2025-08-09T12:57:30.287Z","repository":{"id":65343966,"uuid":"570062369","full_name":"nightwatchjs/nightwatch-plugin-apitesting","owner":"nightwatchjs","description":"Run API tests in Nightwatch using supertest","archived":false,"fork":false,"pushed_at":"2024-05-16T12:15:19.000Z","size":270,"stargazers_count":2,"open_issues_count":5,"forks_count":8,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-11T15:22:47.279Z","etag":null,"topics":["api-testing","mock","mock-server","nightwatch","nightwatchjs","supertest","testing"],"latest_commit_sha":null,"homepage":"https://nightwatchjs.org","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nightwatchjs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-11-24T08:53:03.000Z","updated_at":"2024-05-16T12:15:19.000Z","dependencies_parsed_at":"2023-02-10T14:01:29.888Z","dependency_job_id":"550bb644-de55-4f02-bcec-76ec04c73be8","html_url":"https://github.com/nightwatchjs/nightwatch-plugin-apitesting","commit_stats":{"total_commits":50,"total_committers":6,"mean_commits":8.333333333333334,"dds":0.5,"last_synced_commit":"80421e58e738c19757a8b2ae4740a5ad09dc1a9c"},"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nightwatchjs%2Fnightwatch-plugin-apitesting","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nightwatchjs%2Fnightwatch-plugin-apitesting/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nightwatchjs%2Fnightwatch-plugin-apitesting/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nightwatchjs%2Fnightwatch-plugin-apitesting/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nightwatchjs","download_url":"https://codeload.github.com/nightwatchjs/nightwatch-plugin-apitesting/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248596702,"owners_count":21130748,"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-testing","mock","mock-server","nightwatch","nightwatchjs","supertest","testing"],"created_at":"2024-11-07T14:21:56.279Z","updated_at":"2025-04-12T16:33:15.943Z","avatar_url":"https://github.com/nightwatchjs.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @nightwatch/apitesting\n\n[![npm](https://img.shields.io/npm/v/@nightwatch/apitesting.svg)](https://www.npmjs.com/package/@nightwatch/apitesting)\n[![tests](https://github.com/nightwatchjs/nightwatch-plugin-apitesting/actions/workflows/build.yml/badge.svg?branch=main)](https://github.com/nightwatchjs/nightwatch-plugin-apitesting/actions/workflows/build.yml)\n[![Discord][discord-badge]][discord]\n\n## API Testing in Nightwatch\n\nThis plugin brings support for API testing into Nightwatch. It contains the following features:\n- integration with [supertest](https://www.npmjs.com/package/supertest) for testing HTTP requests\n- built-in mock server based on [express](https://www.npmjs.com/package/express) with support for [sinon](https://www.npmjs.com/package/sinon) assertions on mocked HTTP requests  \n\nRequires Nightwatch 2.6.4 or higher. \n\n## Installation\n\n1) Install the plugin from NPM:\n\n```sh\nnpm i @nightwatch/apitesting --save-dev\n```\n\n2) Edit your `nightwatch.json` (or `nightwatch.conf.js`) file and add the following:\n \n```json\n{\n  \"plugins\": [\n    \"@nightwatch/apitesting\"      \n  ]\n}\n```\n\n3) Disable the browser session\n\nWe also need to turn off the browser session, since we're only doing API testing. This can be accomplished by setting these properties:\n\n```json\n{\n  \"start_session\": false,\n  \"webdriver\": {\n    \"start_process\": false\n  }\n}\n```  \n\n## Configuration\n\nThe plugin has for now only one configuration option, which is weather or not to log the HTTP responses to the console. This can be configured in the `nightwatch.json` (or `nightwatch.conf.js`) config file:\n\n```json\n{\n  \"@nightwatch/apitesting\" : {\n    \"log_responses\": true\n  }\n}\n```\n\n## Usage\n\n### Test Syntax\n\n\u003e All `supertest.request()` calls should be `await`ed. The classic callback syntax is not supported.\n\n### Test API requests with supertest\n[supertest](https://www.npmjs.com/package/supertest) is a popular HTTP request library that is used in many Node.js projects. \n\nUsing `supertest` in Nightwatch allows you to test your API endpoints and assert on the responses using its popular fluent API. \n\n#### Example:\n\n```js\nconst express = require('express');\n\ndescribe('api testing with supertest in nightwatch', function () {\n  let app;\n  let server;\n\n  before(async function(client, done) {\n    app = express();\n    app.get('/api/v1/', function (req, res) {\n      res.status(200).json([\n        {\n          id: 'test-schema-id1'\n        },\n        {\n          id: 'test-schema-id2'\n        }\n      ]);\n    });\n\n    server = app.listen(3000, function() {\n      done();\n    });\n  });\n\n  after(() =\u003e {\n    server.close();\n  });\n\n  it('demo test async', async function({supertest}) {\n    await supertest\n      .request(app)\n      .get('/api/v1/')\n      .expect(200)\n      .expect('Content-Type', /json/);\n  });\n\n});\n```\n\n### Integrated mock server\n\nThe plugin also provides a built-in mock server based on [express](https://www.npmjs.com/package/express) that can be used to assert incoming http requests.\n\n#### API\n- `const mockServer = await client.mockserver.create()` – creates a new mock server instance\n- `await mockServer.setup(definition)` – setup an existing mock server instance with the provided route definition\n   Example:\n    ```js\n    await mockServer.setup((app) =\u003e {\n      app.get('/api/v1/schemas', function (req, res) {\n        console.log('GET /api/v1/schemas called');\n  \n        res.status(200).json([\n          {\n            id: 'test-schema-id1'\n          },\n          {\n            id: 'test-schema-id2'\n          }\n        ]);\n      })\n    });\n    ```\n- `await mockServer.start(port)` – starts an existing mock server instance on the specified port\n- `await mockServer.route(path)` – returns a [sinon spy](https://sinonjs.org/releases/latest/spies/) on the specified route\n\n### Assert on incoming requests\n\nUse the `mockServer.route(path)` method to retrive a spy on the specified route. You can then use the [sinon assertions](https://sinonjs.org/releases/latest/spies/#spyanonymous) to assert on the incoming requests. \n\n#### Example\n\nConsider the previous mock server setup example. If we want to assert that the `GET /api/v1/schemas` route was called, we can do the following:\n\n```js\n  it('demo test', async function(client) {\n    client\n      .assert.strictEqual(mockServer.route.get('/api/v1/schemas').calledOnce, true, 'called once')\n      .assert.strictEqual(mockServer.route.get('/api/v1/schemas').calledTwice, false);\n  });\n```\n\n#### Assert on request headers\n\nWe can also assert on the request headers, for example using the built-in `expect()` assertions API which uses on [chai](https://www.chaijs.com/api/bdd/):\n\n```js\n  it('demo test', async function(client) {\n    const {requestHeaders} = mockServer.route.get('/api/v1/schemas');\n\n    client.expect(requestHeaders).to.have.property('connection', 'close');\n  });\n```\n\n### Assert on incoming post data\n\nWe can also assert on the incoming post data: \n\n1) First setup a post route for the mock server:\n\n```js\nawait mockServer.setup((app) =\u003e {\n  app.post('/api/v1/datasets/', function (req, res) {\n    res.status(200).json({\n      id: 'test-dataset-id'\n    });\n  });\n});\n```\n\n2) Then use the `mockServer.route.post(path)` method to retrive a spy on the specified route. You can then use the [sinon assertions](https://sinonjs.org/releases/latest/spies/#spyanonymous) to assert on the incoming requests. \n\n```js\n  it('demo test', async function(client) {\n    const {requestBody} = mockServer.route.post('/api/v1/schemas');\n\n    await client.assert.deepStrictEqual(requestBody, {name: 'medea'});\n  });\n```\n\nFor waiting for incoming requests tests, you can use the [`waitUntil()`](https://nightwatchjs.org/api/waitUntil.html) command.\n\nExample using waitUntil:\n```js\n  it('demo test', async function(client) {\n    const timeoutMs = 15000;\n    const retryIntervalMs = 500;\n    \n    await client.waitUntil(async function () {\n      const spy = server.route.get('/api/v1/schemas');\n\n      if (spy) {\n        return spy.calledOnce;\n      }\n\n      return false;\n    }, timeoutMs, retryIntervalMs, new Error(`time out reached (10000ms) while waiting for API call.`));  \n  });\n```\n\n\n## License\nMIT\n\n[discord-badge]: https://img.shields.io/discord/618399631038218240.svg?color=7389D8\u0026labelColor=6A7EC2\u0026logo=discord\u0026logoColor=ffffff\u0026style=flat-square\n[discord]: https://discord.gg/SN8Da2X\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnightwatchjs%2Fnightwatch-plugin-apitesting","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnightwatchjs%2Fnightwatch-plugin-apitesting","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnightwatchjs%2Fnightwatch-plugin-apitesting/lists"}