npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@gocardless/stubby

v0.0.10

Published

AJAX Testing Stub Library

Downloads

89

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 against
  • data: an object that should be present in the request data.
  • method: the type of request. Defaults to GET.
  • overrideStub: pass true here to state that this stub should override a matching stub if one exists. Defaults to false.

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 returned
  • data: the body that will be returned as JSON
  • responseOptions: an optional third argument that can set extra options. You can pass in a headers 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