stripe-mock is a mock HTTP server that responds like the real Stripe API. It can be used instead of Stripe's testmode to make test suites integrating with Stripe faster and less brittle.
tomer-stripe Merge pull request #112 from stripe/ignore-stripe-resource
Add x-stripeResource to supported params
Latest commit 17b7132 Sep 14, 2018
Permalink
Failed to load latest commit information.
cert Add option to activate HTTPS and HTTP/2 if client supports it Jul 18, 2018
generator/datareplacer Activate golint for stripe-mock Jul 25, 2018
openapi @ 3d3b4d5 Add x-stripeResource to supportedSchemaFields Sep 14, 2018
param Add support for query parameters on `GET` endpoints Aug 30, 2018
scripts Minor fixes for Docker Hub tagging Aug 31, 2018
spec Add x-stripeResource to supportedSchemaFields Sep 14, 2018
vendor Remove support for YAML files Jul 20, 2018
.dockerignore Leaner Docker image through the use of multi-stage builds Mar 21, 2018
.gitignore Not general, but adding my `TODO.md` to `.gitignore` Apr 26, 2018
.gitmodules Add OpenAPI submodule + bindata/test instructions Jun 21, 2017
.travis.yml Fix deploy condition (`branch` and `tags` are not compatible) Aug 31, 2018
Dockerfile Support simultaneous HTTP and HTTPS Jul 19, 2018
LICENSE License stripe-mock under MIT Dec 5, 2017
Makefile Activate golint for stripe-mock Jul 25, 2018
README.md Simplify usage instructions Sep 14, 2018
bindata.go Add x-stripeResource to supportedSchemaFields Sep 14, 2018
generator.go Don't replace data on non-`POST` endpoints Jul 30, 2018
generator_test.go Don't replace data on non-`POST` endpoints Jul 30, 2018
goreleaser.yml Listen for HTTP and HTTPS simultaneously in .plist Jul 19, 2018
main.go Don't start `HTTPS` with `-port` option specified Aug 29, 2018
main_test.go Merge pull request #108 from stripe/brandur-query-parameters Aug 30, 2018
server.go Add support for query parameters on `GET` endpoints Aug 30, 2018
server_test.go Use customer delete instead of charge (charges cannot be deleted) Aug 30, 2018

README.md

stripe-mock Build Status

stripe-mock is a mock HTTP server that responds like the real Stripe API. It can be used instead of Stripe's test mode to make test suites integrating with Stripe faster and less brittle. It's powered by the Stripe OpenAPI specification, which is generated from within Stripe's API.

Current state of development

stripe-mock is able to generate an approximately correct API response for any endpoint, but the logic for doing so is still quite naive. It supports the following features:

  • It has a catalog of every API URL and their signatures. It responds on URLs that exist with a resource that it returns and 404s on URLs that don't exist.
  • JSON Schema is used to check the validity of the parameters of incoming requests. Validation is comprehensive, but far from exhaustive, so don't expect the full barrage of checks of the live API.
  • Responses are generated based off resource fixtures. They're also generated from within Stripe's API, and similar to the sample data available in Stripe's API reference.
  • It reflects the values of valid input parameters into responses where the naming and type are the same. So if a charge is created with amount=123, a charge will be returned with "amount": 123.
  • It will respond over HTTP or over HTTPS. HTTP/2 over HTTPS is available if the client supports it.

Limitations:

  • It's currently stateless. Data created with POST calls won't be stored so that the same information is available later.
  • For polymorphic endpoints (say one that returns either a card or a bank account), only a single resource type is ever returned. There's no way to specify which one that is.
  • It's locked to the latest version of Stripe's API and doesn't support old versions.

Future plans

The next important feature that we're aiming to provide is statefulness. The idea would be that resources created during a session would be stored for that session's duration and could be subsequently retrieved, updated, and deleted. This would allow more comprehensive integration tests to run successfully against stripe-mock.

We'll continue to aim to improve the quality of stripe-mock's responses, but it will never be on perfect parity with the live API. We think the ideal test suite for an integration would involve running most of the suite against stripe-mock, and then to have a few smoke tests run critical flows against the more accurate (but also slower) Stripe API in test mode.

Usage

If you have Go installed, you can install the basic binary with:

go get -u github.com/stripe/stripe-mock

With no arguments, stripe-mock will listen with HTTP on its default port of 12111 and HTTPS on 12112:

stripe-mock

Ports can be specified explicitly with:

stripe-mock -http-port 12111 -https-port 12112

(Leave either -http-port or -https-port out to activate stripe-mock on only one protocol.)

It can also listen via Unix socket:

stripe-mock -http-unix /tmp/stripe-mock.sock -https-unix /tmp/stripe-mock-secure.sock

Homebrew

Get it from Homebrew or download it from the releases page:

brew install stripe/stripe-mock/stripe-mock

# start a stripe-mock service at login
brew services start stripe-mock

# upgrade if you already have it
brew upgrade stripe-mock

The Homebrew service listens on port 12111 for HTTP and 12112 for HTTPS and HTTP/2.

Docker

# build
docker build . -t stripe-mock
# run
docker run -p 12111-12112:12111-12112 stripe-mock

The default Docker ENTRYPOINT listens on port 12111 for HTTP and 12112 for HTTPS and HTTP/2.

Sample request

After you've started stripe-mock, you can try a sample request against it:

curl -i http://localhost:12111/v1/charges -H "Authorization: Bearer sk_test_123"

Development

Testing

Run the test suite:

go test ./...

Binary data & updating OpenAPI

The project uses go-bindata to bundle OpenAPI and fixture data into bindata.go so that it's automatically included with built executables. Rebuild it with:

# Make sure you have the go-bindata executable (it's not vendored into this
# repository).
go get -u github.com/jteeuwen/go-bindata/...

# Drop into the openapi/ Git submodule and update it (you may have to commit a
# change).
pushd openapi/ && git pull origin master && popd

# Generates `bindata.go`.
go generate

Release

Release builds are generated with goreleaser. Make sure you have the software and a GITHUB_TOKEN:

go get -u github.com/goreleaser/goreleaser
export GITHUB_TOKEN=...

Commit changes and tag HEAD:

git pull origin --tags
git tag v0.1.1
git push origin --tags

Then run goreleaser and you're done! Check releases (it also pushes to the Homebrew tap).

goreleaser --rm-dist