@gocardless/stubby
v0.0.10
Published
AJAX Testing Stub Library
Downloads
89
Maintainers
Readme
This library is legacy and will be modified to help us move away from it, and will not be maintained with the plan to deprecate this library later this year (2018).
If you require a stubbing library see: Pretender
Stubby
Continuous Integration
Currently this project is tested in Circle CI v1 which is past it's sunset and could be switched off at any time. There are currently no plans to migrate this project as no major changes are being made, and no plans to support this longer term. If you plan on making major changes to this project we recommend you migrate it to use Circle CI V2 first.
AJAX Testing Stub Library
Stubby is a rich API on top of Pretender to allow for browser integration testing and AJAX endpoint mocking.
Stubby will also validate any stubs given to it. URL parameters are treated as significant along with request parameters. You can stub request HTTP headers, url parameters, the response code and body. Stubby will match incoming requests against the stubs that have been defined. The library is primarily built for testing JSON APIs; JSON requests and responses are decoded for you.
Stubby allows for features to be added as plugins, such as JSON schema validation of requests and mocks, along with potential additional verifications for mocks preventing invalid mocks from being created. The library comes with a module for validating stubs against a JSON Schema.
Installing Stubby
There are two ways you can use Stubby. The first is to simply add dist/stubby-bundle.min.js
to your page. This is a Browserify compiled build that includes Stubby and all its dependencies.
If you'd rather deal with loading the dependencies yourself, you should include stubby.js
along with its dependencies, which are:
If you find any bugs or issues with Stubby, please feel free to raise an issue on this repository.
Usage Examples:
See the demo in example/demo.html
by running npm run demo
.
Server code:
stubby.stub({
url: '/foo',
params: { b: 1 },
}).respondWith(200, { b: 1});
This code stubs out a server at that responds to GET /foo?b=1
with {b:1}
.
Client-side code:
$.get('/foo?b=1', function(response) {
if (response.body['b'] === 1) {
alert('ok :)');
} else {
alert('fail');
}
})
Stubbing a URL
Given an instance of stubby, you can call stub
to stub a URL. This returns a Stubby.StubInternal
object, that you can then call respondWith
to define what Stubby should return:
stubby.stub(options).respondWith(status, data, responseOptions)
The allowed options for a stub are:
url
: The URL of the request. Can include query params, Stubby will strip them for you and match against them too.params
: An object of query parameters that should be matched against. If these are given, Stubby will use these over any query parameters in the URL.headers
: a list of headers for Stubby to match againstdata
: an object that should be present in the request data.method
: the type of request. Defaults toGET
.overrideStub
: passtrue
here to state that this stub should override a matching stub if one exists. Defaults tofalse
.
If you try to stub a request that is already stubbed, Stubby will error. You should first call stubby.remove(options)
to remove the stub, and then restub it.
You should also consult the Stubby specs for many examples of how to stub requests.
respondWith
takes three arguments:
status
: the status code that will be returneddata
: the body that will be returned as JSONresponseOptions
: an optional third argument that can set extra options. You can pass in aheaders
object here to set response headers.
An instance of Stubby
also has the following methods that can be called:
addModule(module)
Adds a module to Stubby. See below for what these modules can do and how to write them.
passthrough(url)
By default Stubby blocks all requests, and will error if it gets a request that it can't match to a Stub. You can use this method to tell Stubby that it's fine to let requests matching this URL to hit the network. stubby.passthrough('/foo')
would mean any GET
request to /foo
hits the network. It is currently only possible to passthrough on GET
requests.
verifyNoOutstandingRequests()
When called, Stubby will check that every stub that it has been given has been called at least once, and error if it hasn't. This is useful to perform at the end of a test, to ensure all stubs were matched.
Modules:
Stubby provides an API to add functionality through modules.
How to setup a module:
The included modules in the modules/
folder are optional, officially supported parts of this project to supplement the functionality of Stubby but also to keep the core lightweight. Modules are registered by passing an instance of a module to addModule
:
var addonModule = new RandomAddonModule();
var stubby = new window.Stubby();
stubby.addModule(addonModule);
#### Modules API:
A module needs to expose an javascript object or function with a prototype or method called register. The register method is passed an object that listeners within that class can be registered with:
function DemoModule(api_version){
// Method to register the module as a handler.
this.register = function(handler) {
// handler.on(event, callback(request, stub), callback context);
// Handler called when the route is setup calling `.stub`.
handler.on('setup', function(req, stub) { }, this);
// Handler called when a route is being matched (allows for changes or checks before matching routes).
handler.on('routesetup', function(req, stub) { }, this);
// Handler is called when a request is about to be fuffiled by the passed in matching route
handler.on('request', function(req, stub) { this.inject_api_version(stub); }, this);
};
this.inject_api_version = function(stub) {
stub.response.headers['api-version'] = api_version;
};
}
Included Modules:
- schema-validator:
While Stubby doesn't support JSON Schema validation out of the box, the included schema-validator module validates stubs against a JSON hyperschema.
To setup the validator, add a schema like so:
var stubby = new Stubby();
var validator = new window.StubbySchemaValidator();
validator.addSchema('/', schemaJSON);
stubby.addModule(validator);
- chaos-monkey:
A demo module that responds with random http status codes instead of the ones specified with the stub with the option {chaos: true}
set in the stub.
It also verifies that the response http status is equal to 42 in order to allow for chaos.
This module demonstrates how to write a simple module to integrate within the stubby framework, for usage examples, see the definitions file and corresponding spec.
Development:
When you clone the repo, you should ensure all dependencies are installed:
npm install
bower install
You can run npm test
to run all the tests.
In order to recompile the browserify modules, run ./script/build
to rebuild. To force a build, run ./script/build -f
.
If you don't want to use the Browserify build, manually take stubby.js
, its dependencies and any modules from the modules
folder.
Limitations:
Since stubby was created for JSON APIs, it might be better to use the raw pretender API instead of stubby for other types of data.
Additionally, Pretender doesn't allow for mocking JSONP or cross-origin ajax requests, so stubby only works for the same hostname/protocol/port ajax requests.
Changelog
V0.0.6
- fix schema validation for non-object request payloads
V0.0.5
- print expected stub when no stubs where found
V0.0.4
- allow stubs to have response headers specified
V0.0.3
- allow stubs to override existing match with
overrideStub
option
V0.0.2
- stop skipping data matches in schema validation plugin
- if a request has data but the stub has none defined, it will now match that request to that stub
##### V0.0.1
- initial release