TwinStub brings stateful, deterministic API simulation to local testing

A new open-source project called TwinStub has emerged to help development teams simulate complex API integrations locally. Released on GitHub in October 2026, this tool allows engineers to define stateful scenarios in YAML files that play back as real HTTP servers. It is designed specifically for teams building software that interacts with external providers like payment gateways or logistics platforms.

What happened

TwinStub addresses a common pain point in software development: testing the unhappy paths of third-party integrations. When companies build systems that rely on external APIs, their most difficult bugs often occur not during standard operations, but during rare events such as chargebacks, identity verification failures, or delayed webhooks. Traditional mock servers typically handle one request at a time and lack memory, making it difficult to simulate a sequence of events that unfold over days or weeks.

This new tool models an integration as a state machine. It maintains session state, meaning that a specific endpoint can return different responses based on previous interactions. For example, a request to check a payment status might initially return "processing," then "succeeded," and finally "chargeback" as the simulated timeline progresses. This allows developers to compress long-term processes into seconds for testing purposes. The tool runs as a single binary written in Go, requiring no cloud registration or external services, and is distributed under an MIT license.

The core value proposition is that TwinStub acts as a stand-in for the external provider. The code under test is the client application itself, which must handle requests, parse responses, verify webhook signatures, and update internal ledgers. By simulating the provider, developers can trigger branches in their code that are otherwise hard to reach, such as handling out-of-order event delivery or verifying HMAC signatures on incoming webhooks. The project includes a command-line interface for serving simulations, validating configuration files, and initializing demo scenarios.

Key details

• Stateful simulations: Unlike static mocks, TwinStub uses sessions keyed by headers, query parameters, or body fields to track the state of each client interaction over time.
• Webhook chains: It supports delayed, HMAC-signed webhooks with exponential retries and jitter, mimicking the behavior of major providers like Stripe.
• Time compression: Developers can use a time-scale flag to accelerate long-duration flows, turning thirty-day processes into hours or minutes for rapid testing.
• Single binary deployment: The tool is a self-contained Go binary that runs locally or in continuous integration pipelines without requiring Java, Electron, or cloud connectivity.
• Diagnostic feedback: When a request does not match any defined scenario, the server returns a detailed error message explaining which matchers failed and why, aiding in debugging.
• Chaos engineering features: Users can inject latency, drop TCP connections, or return arbitrary server errors to test how their application handles transport faults.

Background

To understand the utility of TwinStub, it helps to distinguish between simple mocking and stateful simulation. A basic mock server responds to a specific URL with a predefined payload. It does not remember what happened in previous requests. This works well for testing happy paths where a single request yields a single expected response. However, modern integrations are often event-driven and stateful. A payment might be authorized, captured, refunded, and then charged back weeks later. Each step changes the state of the transaction.

Webhooks are asynchronous notifications sent by external services to your application when an event occurs. Testing webhooks is notoriously difficult because they require a publicly accessible URL and involve cryptographic signatures to ensure authenticity. In a local development environment, receiving these webhooks usually requires tunneling services or complex network configurations. TwinStub simplifies this by acting as the sender, generating signed webhooks that fire according to the defined scenario. This allows developers to test their webhook handlers, including signature verification and idempotency logic, without relying on the actual third-party service.

Why it matters

For teams that run their own software, reliability in integrations is critical. Bugs in integration code often lead to financial discrepancies, such as double-charging customers or failing to release reserved inventory after a failed payment. These issues are expensive to fix in production and difficult to reproduce in staging environments. By providing a deterministic way to simulate these rare events, TwinStub enables developers to catch these bugs before deployment. It shifts the testing burden from manual verification against live sandboxes to automated tests that can run in every build.

Furthermore, the ability to run these simulations locally without cloud dependencies enhances security and speed. Developers do not need to share API keys or sensitive data with external mocking services. The tool’s design ensures that state is kept in memory, which means each test run starts fresh, preventing cross-test contamination. This determinism is essential for continuous integration pipelines, where flaky tests can slow down development velocity. The inclusion of a validation command allows teams to check their scenario definitions for errors before running them, ensuring that the simulation accurately reflects the intended behavior.

However, there is a limitation to acknowledge. The accuracy of the simulation depends entirely on the quality of the YAML scenario definition. If the scenario mismodels the real provider’s behavior, the tests will pass even if the code is incorrect for the real world. Therefore, it is recommended to validate the response shapes against the provider’s sandbox once, and then use TwinStub to explore the edge cases that the sandbox cannot easily trigger.

What you can do

• Install TwinStub using the Go toolchain or Docker to start simulating API interactions in your local environment.
• Define your integration scenarios in YAML, focusing on state transitions and webhook sequences rather than just static responses.
• Use the time-scale feature to accelerate long-running processes, allowing you to test month-long workflows in minutes.
• Implement signature verification in your webhook handlers and use TwinStub’s HMAC signing to ensure your security logic works correctly.
• Run the validation command in your CI pipeline to catch configuration errors early and prevent broken simulations from blocking builds.
• Test chaos scenarios by injecting latency or connection drops to verify that your application handles network failures gracefully.