node-defacto discovers your de facto API contract, represented as an OpenAPI/Swagger
specification. As the API provider testing your own service, defacto in conjunction
with a swagger-diff tool allows you to make two types of assertions:
- The contract specification is up-to-date and correct
- Everything in the contract specification has been tested
As the API consumer testing your application against a stub, defacto and
swagger-diff allow you to verify that the spec you're writing tests against is
compatible with the spec given by the API provider.
node-defacto needs to be initialized before any tests are run. In mocha, you can
use a root-level before hook to do the trick.
This might be the initialization function for mountebank:
// Outside of any describe block
before(function () {
require('node-defacto').capture({
title: 'mountebank',
version: '1',
baseURL: 'http://localhost:2525/',
paths: ['/', '/imposters', '/imposters/{port}', '/config', '/logs'],
filename: 'test-swagger.json'
});
});
Then execute your service test suite against your API. node-defacto doesn't work
with your unit tests. It can only capture the test contract expectations for those
tests that use node's http module to call your API over the wire. In the example
above, all test traffic sent to http://localhost:2525/ is analyzed, which represents
the host and basePath elements at the root of the OpenAPI specification.
The complete OpenAPI specification that the tests expect is captured in
test-swagger.json, which can be diffed to the actual spec for the assertions.
There are two diffing tools I'm aware of and evaluating:
node-defacto wraps the http module, capturing all client requests and responses
that match the host and basePath given in the first parameter to the capture
function. Each time a new OpenAPI path and operation is detected, it is added
to the spec. Each time defacto detects a new input parameter, it adds it to the
spec. Each time a new response is detected, it is added to the spec. Every request
and response JSON body is captured, and all fields and types are added to the spec.
node-defactoassumes JSON.- It assumes you're testing against an HTTP API rather than an HTTPS one
- It assumes no tests are running in parallel
- It does nothing with headers, more or less assuming application/json (easy to fix)
- I think it assumes you never use chunked encoding and always write the request body in one fell swoop (not tested)
- It does not detect required fields. Future versions can assume required if ALL tests pass it in
- It makes a best effort at type inference. Should be extensible in the future.
node-defacto is not written in ES6 because it needs to support the oldest
supported version of node (4.0), which does not fully support ES6.
./build should run the build, or (assuming you've previously run an npm install and
an npm install -g grunt-cli), grunt will do the same.