DOCSEARCHbyAlgolia
Submit Docs

stripe-mock

repository·master·Indexed 23 days ago

https://github.com/stripe/stripe-mock

A lightweight, stateless HTTP mock server used to simulate the Stripe API for basic sanity checks in SDKs and test suites. Powered by the Stripe OpenAPI specification, it validates request parameters and provides hardcoded responses based on resource fixtures. It supports custom OpenAPI specs, custom fixtures, and can be run via Go, Homebrew, or Docker.

Tokens
2.5K
Snippets
11
Records
18
Agent score
80%

What's inside stripe-mock

  1. What is stripe-mock and when to use it

    master

    stripe-mock is a mock HTTP server that simulates the Stripe API. It is designed for basic sanity checks, such as validating that an SDK hits the correct URLs and sends the expected parameters. It is powered by the Stripe OpenAPI specification, ensuring it stays up-to-date with the latest methods and fields.

    Key Characteristics

    • Stateless: Data sent in POST requests is validated but not stored. Subsequent requests will not reflect changes made in previous ones.
    • Hardcoded Responses: Responses are generated from resource fixtures and resemble real Stripe data types, but they are not necessarily realistic based on your input.
    • Parameter Reflection: If you send a valid parameter (e.g., amount=123), the mock will reflect that value in the response (e.g., "amount": 123).
    • Validation: Uses JSON Schema to check incoming request parameters, though validation is not as exhaustive as the live API.

    When NOT to use stripe-mock

    • Sophisticated Testing: Do not use it for complex logic or stateful workflows.
    • Specific Error Testing: It does not support testing for specific error responses (it will return a success response instead).
    • Regression Suites: For robust regression testing, use the VCR gem or define your own custom mocks.
    • Integration Validation: Always test actual Stripe integration changes against Stripe testmode.

  2. Generate a self-signed certificate for localhost HTTPS

    master

    If you need to run stripe-mock with HTTPS using a custom certificate, you can generate a new self-signed certificate for localhost using OpenSSL. This allows the mock server to serve requests over an encrypted connection.

    openssl req -x509 -newkey rsa:4096 -keyout cert/key.pem -out cert/cert.pem -days 3650 -nodes -subj '/CN=localhost'

  6. Update bundled certificates in stripe-mock

    master
    Because certificates are bundled directly into the stripe-mock executable, simply replacing the .pem files is not enough. After generating or replacing your certificates, you must run the go generate command to re-embed the new files into the Go binary using go-bindata.
    go generate

  7. How DoubleSlashFixHandler works

    master

    DoubleSlashFixHandler is a specialized HTTP handler that wraps an existing http.Handler (an http.Mux). It deduplicates double slashes in incoming request paths (e.g., converting //v1/charges to /v1/charges) before passing the request to the underlying handler. This emulates the behavior of the real Stripe API, which responds normally to requests containing double slashes, whereas standard Go behavior might trigger a 301 redirect.

    Use this when you want to ensure your mock server is as permissive as the real Stripe API regarding path formatting.

    type DoubleSlashFixHandler struct {
	Mux http.Handler
}

func (h *DoubleSlashFixHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
	r.URL.Path = strings.Replace(r.URL.Path, "//", "/", -1)
	h.Mux.ServeHTTP(w, r)
}

  8. Run stripe-mock via CLI

    master
    The stripe-mock binary can be executed with various flags to configure the server's network interface, protocol (HTTP/HTTPS), and data sources (OpenAPI specs and fixtures). By default, it runs an HTTPS server. You can use it to serve standard Stripe API responses or provide custom JSON fixtures and OpenAPI specifications for testing.

  10. Run stripe-mock with CLI options

    master

    You can run the stripe-mock binary with various flags to configure ports and protocols.

    Default Behavior

    Running stripe-mock without arguments listens on HTTP port 12111 and HTTPS port 12112.

    Custom Ports

    Specify ports explicitly using -http-port and -https-port. You can omit one to enable only a single protocol.

    To let the system select a port automatically, pass 0.

    Unix Sockets

    You can listen via Unix sockets using -http-unix and -https-unix.

  11. Initialize a new StubServer

    master

    NewStubServer creates a new instance of StubServer, which is the core component responsible for handling incoming HTTP requests and responding based on the provided OpenAPI specification and fixtures.

    Arguments:

    • fixtures: A pointer to a spec.Fixtures object.
    • spec: A pointer to a spec.Spec object.
    • strictVersionCheck: If true, any request sending an explicit Stripe-Version header must match the version defined in the OpenAPI spec.
    • verbose: If true, the server will print detailed information about extracted IDs, response schemas, and request data to standard output.
    func NewStubServer(fixtures *spec.Fixtures, spec *spec.Spec, strictVersionCheck, verbose bool) (*StubServer, error)

  12. Load OpenAPI spec from a JSON file

    master

    The LoadSpec function allows you to load an OpenAPI specification from a JSON file. If the specPath argument is an empty string, the function uses the OpenAPI spec embedded within the binary.

    Note: The provided path must be a valid .json file.

    func LoadSpec(embeddedSpec []byte, specPath string) (*spec.Spec, error)