octokit-fixtures

Fixtures for all the octokittens

Records requests/responses against the GitHub REST API and stores them as JSON fixtures for usage as a standalone http mock server or as a Node module.

• Usage
  • Standalone mock server
  • As node module
    • fixtures.mock(scenario)
    • fixtures.get(scenario)
• How it works
  • Recording
  • Updating fixtures
  • Automated pull requests when API change
  • Standalone server
  • Normalizations
• Local development
  • Record
  • Server
  • Tests
  • Coverage
• License

Usage

Standalone mock server

Download binary for your os from the latest release.

Alternatively, you can also install octokit-fixtures as a global npm package, if you prefer that:

# npm install --global octokit-fixtures
octokit-fixtures-server

It currently loads all mocks from /fixtures/api.github.com. Once started, you can send requests

curl -H'Accept: application/vnd.github.v3+json' http://localhost:3000/repos/octocat/hello-world
# returns response from fixture

As node module

Currently requires node 8+

fixtures.mock(scenario)

fixtures.mock(scenario) will intercept requests using nock. scenario is a String in the form <host name>/<scenario name>. host name is any folder in fixtures/. scenario name is any filename in the host name folders without the .js extension.

const https = require('https')
const fixtures = require('octokit-fixtures')

fixtures.mock('api.github.com/get-repository')
https.request({
  method: 'GET',
  hostname: 'api.github.com',
  path: '/repos/octocat/hello-world',
  headers: {
    accept: 'application/vnd.github.v3+json'
  }
}, (response) => {
  console.log('headers:', response.headers)
  response.on('data', (data) => console.log(data.toString()))
  // logs response from fixture
}).end()

For tests, you can check if all mocks have been satisfied for a given scenario

const mock = fixtures.mock('api.github.com/get-repository')
// send requests ...
mock.done() // will throw an error unless all mocked routes have been called

fixtures.get(scenario)

fixtures.get(scenario) will return the JSON object which is used by nock to mock the API routes. You can use that method to convert the JSON to another format, for example.

How it works

octokit-fixtures provides fixtures that can be used by automated tests for GitHub API clients, either as standalone mock server or as a Node module.

The fixtures are recorded programatically (see scenarios/ folder) by sending requests against the GitHub REST API and recording both requests and responses into JSON files (see fixtures/ folder).

Recording

The record task normalizes requests and responses before storing them in order to remove changing values like time stamps and counts. Afterwards the new fixtures are compared to the existing ones. If a change occurs, an error is logged.

Updating fixtures

The stored fixtures can be updated by running bin/record.js --update.

To create a new scenario

1. create a new file in the scenarios folder that matches the host name you send requests to. A scenario is a *.js which can export
   • axios request config
   • an array of axios request configs
   • a function that returns a Promise
2. Run bin/record.js. It should log something like

   ⏯  api.github.com: Get root ...
   ❌  This looks like a new fixture
   

3. If there are no other changes, you can create the new fixtures by running bin/record.js --update. Now it should log something like

   ⏯  api.github.com: Get root ...
   📼  New fixtures recorded
   

4. Running bin/record.js again will show that all fixtures are up-to-date now.

Automated pull requests when API change

In order to keep the fixtures up-to-date with GitHub’s and GitHub Enterprise’s APIs, the record task is run daily utilizing Travis Cron Jobs. If a change in the fixtures occurs, a pull request is opened (or updated) in order to notify the maintainers who can then release a new breaking version of the octokit-fixtures and notify developers of the update.

Standalone server

The standalone http mock server is a simple express app which uses the http-proxy-middleware package to proxy requests to the mocked routes based on the existing fixtures.

Normalizations

• All timestamps are set to the time of the GitHub Universe 2017 keynote
  Dates are set in different formats, so here are a few examples
  • UTC in seconds: 2017-10-10T16:00:00Z (e.g. updated_at)
  • GMT date string: Tue, 10 Oct 2017 16:00:00 GMT (e.g. Last-Modified header)
  • UNIX timestamp in seconds: 1507651200000 (e.g. X-RateLimit-Reset header)
• All counts are set to 42
  for example: forks_count, open_issues_count
• Rate limits
  • for unauthenticated requests, X-RateLimit-Remaining is set to 59.
  • for authenticated requests, X-RateLimit-Remaining is set to 4999.
• Random things
  Fill random headers like ETag or X-GitHub-Request-Id and auth tokens with 0s.
• Content-Length header is re-calculated after normalization of the response body

Local development

Test users / organization

GitHub created test user accounts and an organization for the octokit fixtures:

	octokit-fixture-user-a (user) Main user, has unlimited private repositories
	octokit-fixture-user-b (user) Secondary user, private repositories only
	octokit-fixture-org (org) Main organization, unlimited private repositories, unlimited seats

Record

Some scenarios require a user token with full access. Create one and then set the FIXTURES_USER_ACCESS_TOKEN environment variable. You can create a local .env file if you like, it is parsed using dotenv.

Run scenarios from scenarios/** against the real GitHub APIs and compare responses to previously recorded fixtures

node bin/record

If there are changes, you can updated the recorded fixtures

node bin/record --update

To record a selected scenarios, pass their names to the record command. You can combine that with the --update flag.

node bin/record api.github.com/get-root api.github.com/get-repository

Server

Start the server with

node bin/serve

Tests

Run integration & unit tests with

npm test

Run the end-to-end test with

test/end-to-end/server-test.sh

Coverage

After running tests, a coverage report can be generated that can be browsed locally.

npm run coverage

Releases

Releases are automated using semantic-release. The following commit message conventions determine which version is released:

1. fix: ... or fix(scope name): ... prefix in subject: bumps fix version, e.g. 1.2.3 → 1.2.4
2. feat: ... or feat(scope name): ... prefix in subject: bumps feature version, e.g. 1.2.3 → 1.3.0
3. BREAKING CHANGE: in body: bumps breaking version, e.g. 1.2.3 → 2.0.0

Only one version number is bumped at a time, the highest version change trumps the others.

The server binaries are currently not generated and uploaded automatically. To generate them run npx pgk ., then upload the resulting binaries to the respective release. We plan to automate that process: # – pull requests welcome 🤗

License

MIT