How do we use Speakeasy to generate a mock server from our OpenAPI spec for SDK and integration tests?

Most teams can generate SDKs from an OpenAPI spec. Fewer have a reliable, repeatable mock server to actually exercise those SDKs and their integration tests on every commit. That’s the gap Speakeasy is designed to close: same OpenAPI, multiple artifacts—SDKs, CLIs, and (for many teams) a mock or “fake” backend you can run locally or in CI.

Quick Answer: Speakeasy doesn’t ship a standalone “mock server generator” today, but you can use your OpenAPI spec plus Speakeasy-generated SDKs, CLIs, and test harnesses to simulate your API for SDK and integration tests. The pattern is: generate artifacts from OpenAPI, stand up a lightweight fake or stub server, and point your SDK/CLI tests at that endpoint under test.

---

Frequently Asked Questions

Can Speakeasy generate a mock server directly from my OpenAPI spec?

Short Answer: Not yet as a one-click feature, but you can pair Speakeasy-generated SDKs/CLIs with a lightweight stub or fake backend to get a repeatable mock environment for SDK and integration tests.

Expanded Explanation:
Today, Speakeasy’s generation pipeline is OpenAPI → SDKs, CLIs, Terraform providers, Docs MCP, and MCP servers—not a dedicated “mock server binary.” For most teams, a fully realistic mock is overkill; what they need is a predictable, contract-aligned environment to validate SDK behavior, auth flows, and pagination/retries on every commit.

The practical pattern is: use Speakeasy to generate idiomatic, type-safe SDKs from your OpenAPI, then bring a simple stub server (or framework-based test server) that implements the same routes and shapes. Because the SDK and tests are driven off the same spec, drift is minimized: when the spec changes, your SDK and test expectations change alongside it, without hand-editing boilerplate client code.

Key Takeaways:

• Speakeasy focuses on OpenAPI-driven clients (SDKs, CLIs, Terraform, MCP), not a dedicated mock server binary.
• You can still achieve contract-aligned “mock” behavior by combining generated SDKs with a stub/fake backend tied to the same OpenAPI spec.

---

How do I set up a mock-style test flow using Speakeasy for SDK and integration tests?

Short Answer: Generate your SDK from OpenAPI with Speakeasy, implement a lightweight stub server that mirrors your spec, and configure your tests to hit that stub server’s base URL.

Expanded Explanation:
The core idea is to keep OpenAPI as the single source of truth. Speakeasy turns that spec into SDKs and CLIs; you then stand up a simple in-process or standalone stub server that exposes the same paths and response shapes. Your tests call the SDK (or CLI) exactly as a consumer would, but the requests are routed to your stub instead of a live environment.

Because the SDK is generated, you’re not testing your own HTTP plumbing—you’re testing your contract and your behavior. This fits naturally into the Speakeasy workflow: “upload your OpenAPI,” “generate artifacts,” “ship with every commit” via CI PRs. The only addition is a small test server and some fixtures.

Steps:

1. Generate your SDK with Speakeasy

   • Upload your OpenAPI spec in the Speakeasy app or via the Speakeasy CLI.
   • Generate your SDK in TypeScript, Python, Go, Java, C#, PHP, or another language your team uses.
   • Commit the generated SDK package or keep it as a submodule in your integration tests.

2. Stand up a stub or fake backend

   • Use your preferred language/framework to create a simple HTTP server that exposes the same paths as your OpenAPI spec.
   • Return static or fixture-based JSON bodies that satisfy the schemas in your OpenAPI.
   • Optionally, emulate pagination, retries, and auth flows so you can validate Speakeasy’s generated behavior end to end.

3. Wire your integration tests to the stub server

   • Configure the SDK’s base URL (often via environment variable) to point at http://localhost:<port> or a CI test container.
   • Write tests that use the SDK methods (not raw HTTP) to call your stub server and assert on responses, errors, and edge cases.
   • Run these tests in CI as part of the same pipeline that uses Speakeasy to keep SDKs up to date.

---

What’s the difference between a full mock server and using Speakeasy-generated SDKs with stubs/fakes?

Short Answer: A full mock server tries to simulate your entire API automatically; Speakeasy focuses on generating idiomatic clients and tooling, letting you keep the “server side” thin, explicit, and test-focused.

Expanded Explanation:
Dedicated mock server generators aim to read your OpenAPI and stand up a full HTTP server with autogenerated handlers and fake data. That can be useful early, but it often drifts from reality once real business logic and auth rules appear. You then have two server surfaces to maintain.

With Speakeasy, the emphasis is on the consumer side: SDKs in multiple languages, CLIs, Terraform, and MCP, all generated from the same OpenAPI. Instead of a one-size-fits-all mock server, you implement just enough stub behavior to support the test cases you care about—usually in the same language and test framework your team already uses. The spec still anchors everything, but you don’t accidentally create a second “API” that diverges over time.

Comparison Snapshot:

• Option A: Dedicated mock server generator

  • Reads OpenAPI, auto-creates handlers, and returns generic fake data.
  • Risk of drift from real auth/business logic; can be heavy to run and customize.

• Option B: Speakeasy SDKs + custom stub/fake server

  • Speakeasy owns the client side (SDKs, CLIs, Terraform, MCP) from the same OpenAPI.
  • You implement a slim, explicit stub server that mirrors the routes you actually test.

• Best for:

  • Teams who want contract-aligned tests and idiomatic SDKs across languages, without maintaining a full parallel “mock backend.”

---

How would I actually implement a stub server and tests around a Speakeasy-generated SDK?

Short Answer: Use your normal web framework to build a tiny in-memory server, configure the SDK’s base URL to point at it, and drive test flows through the generated SDK just like a real integration.

Expanded Explanation:
Once you’ve generated an SDK via Speakeasy, your test implementation is straightforward: start a server in test setup, seed it with fixtures, then hit it through the SDK. The key is to keep everything driven from OpenAPI: schemas, routes, and error shapes should map back to your spec so updates are predictable.

A common pattern is:

• Unit tests: mock the SDK at the method layer inside your consumers.
• Integration tests: use the real Speakeasy-generated SDK against a stub server.
• End-to-end tests: use the same SDK against your staging or dev environment.

What You Need:

• An OpenAPI spec that reflects your real API contract (as used by Speakeasy).
• A test harness (e.g., Jest, pytest, JUnit, Go test) and a lightweight HTTP server or framework for stubbing.

---

How does this approach fit into a broader testing and release strategy with Speakeasy?

Short Answer: Treat OpenAPI as the contract, Speakeasy as the artifact generator, and your stub/mock layer as the safety net that lets you “ship with every commit” without breaking SDK consumers.

Expanded Explanation:
Speakeasy’s core value is operationalizing change: when your API evolves, you don’t manually patch SDKs in seven languages or hand-update CLIs. You update the OpenAPI spec, Speakeasy generates new artifacts, and your CI pipeline validates them via tests before anything reaches users. The mock/stub pattern enhances this by giving you a safe environment to exercise generated SDKs and CLIs without relying on a flaky shared backend.

You can:

• Run integration tests against a stub server for fast, deterministic checks.
• Run smoke tests against a dev/staging environment using the same Speakeasy SDKs.
• Use the Speakeasy CLI or MCP tooling in “agent-ready” modes to validate that agents and humans see consistent behavior.

Why It Matters:

• Reduced drift and regressions: When OpenAPI changes, Speakeasy regenerates SDKs—and your tests against the stub server catch mismatches before they hit production.
• Faster, safer releases: With automated generation plus automated tests, you can ship SDK updates with every API commit instead of batching risky, manual releases.

---

Quick Recap

You can absolutely use Speakeasy as part of a mock-friendly workflow for SDK and integration tests, even though it doesn’t yet ship a single “mock server binary.” The pattern is: keep your OpenAPI spec as the source of truth, let Speakeasy generate idiomatic SDKs and tooling from it, and stand up a thin stub/fake backend that mirrors the same paths and schemas. Your integration tests then run through the generated SDKs against this stub, catching contract issues early and keeping your multi-language clients in lockstep with your API.

Next Step

Get Started