Speakeasy + Arazzo workflows: how do we add multi-step contract tests (setup/teardown) to our pipeline?

Most teams hit the same wall the moment they try to move beyond “hello world” contract tests: a single request/response isn’t enough. You need setup calls to create data, multi-step flows to exercise real behavior, and teardown so your test suite doesn’t salt your staging environment with junk. Arazzo workflows plus Speakeasy’s contract testing are how you get there without duct tape.

Quick Answer: Use Arazzo workflows to define multi-step scenarios (including setup and teardown operations) on top of your OpenAPI, then run them via Speakeasy’s contract testing CLI or CI job so they execute as part of your pipeline with real auth, real data, and pass/fail signals.

Frequently Asked Questions

How do Arazzo workflows help with multi-step contract tests in Speakeasy?

Short Answer: Arazzo lets you describe multi-step API workflows—setup, main flow, and teardown—in a machine-readable spec that Speakeasy can execute as contract tests against your real API.

Expanded Explanation:
Single-endpoint contract tests catch schema drift. Multi-step Arazzo workflows catch “reality drift”: the ways your API breaks when endpoints are combined like a real client would. With Arazzo, you define a workflow that chains operations from your OpenAPI spec, passes data between steps, and marks which steps are setup, core test logic, and teardown. Speakeasy consumes both the OpenAPI spec and the Arazzo workflow to run end‑to‑end contract tests that verify not just response shapes but behavior across a full scenario.

Because Speakeasy is OpenAPI-native, the same source of truth that drives your SDKs, Terraform provider, CLI, and MCP tools also drives these workflows. When your API changes, you update the spec, update the workflow, and Speakeasy runs the new multi-step tests automatically as part of CI.

Key Takeaways:

• Arazzo workflows describe real-world, multi-step API flows (including setup/teardown) on top of your OpenAPI.
• Speakeasy can execute these workflows as contract tests, catching behavioral regressions that single-call tests miss.

---

How do I add a multi-step Arazzo workflow (with setup and teardown) to my pipeline?

Short Answer: Define your workflow in an Arazzo document, wire it to your OpenAPI operations, then call Speakeasy’s contract testing CLI from CI (GitHub Actions, GitLab, etc.) as a stage that runs on every commit or PR.

Expanded Explanation:
The process looks like any other Speakeasy workflow: start from your OpenAPI spec, add a machine-readable description of the flows you care about, then let CI run it with every change. You’ll create an Arazzo file (YAML/JSON) that references your operations (e.g., POST /users, GET /users/{id}, DELETE /users/{id}), declare inputs, and define the step ordering, including setup and teardown.

In CI, the Speakeasy CLI runs against your spec and your workflow file, hitting a real environment (usually staging) with real auth. The CLI surfaces a pass/fail result and detailed logs per step so you can see exactly where a contract broke—schema mismatch, status code, or a downstream effect like “user was never deleted.”

Steps:

1. Author your Arazzo workflow file

   • Create workflows/user-lifecycle.yaml (or similar) and define:
     • workflowId, summary, and description.
     • A steps array referencing operations defined in your OpenAPI by operationId.
     • Dependencies such as “create user” → “fetch user” → “delete user”.
     • Explicit setup steps (creating test data) and teardown steps (cleaning up resources).

2. Wire the workflow to Speakeasy contract tests

   • Ensure your OpenAPI spec is checked into the repo (e.g., openapi.yaml).
   • Configure Speakeasy to read both openapi.yaml and your Arazzo file.
   • Define environment variables for base URL, auth tokens, and any workflow parameters (e.g., SPEAKEASY_TEST_BASE_URL, SPEAKEASY_TEST_TOKEN).

3. Add a CI job to run the workflow on every change

   • In GitHub Actions, add a job like speakeasy-contract-tests that:
     • Installs the Speakeasy CLI.
     • Exports your API key and test environment config.
     • Runs speakeasy test --openapi ./openapi.yaml --workflow ./workflows/user-lifecycle.yaml.
   • Make the job required for merges so every schema or behavior change is validated by your multi-step Arazzo tests before it hits production.

---

What’s the difference between single-call contract tests and Arazzo-based multi-step workflows?

Short Answer: Single-call tests validate one endpoint in isolation; Arazzo workflows validate full scenarios where multiple endpoints interact, including setup and teardown.

Expanded Explanation:
Single-call tests are great guardrails against obvious regressions: “did we change the response type of GET /users/{id}?” or “did we accidentally start returning 500 instead of 4xx on validation errors?” They map 1:1 to OpenAPI operations and mostly focus on response contracts and simple invariants.

Arazzo workflows are about behavior across time. You define sequences like “create → verify → update → delete,” pass IDs and tokens between steps, and assert that each step can only succeed if the previous ones behaved correctly. This captures subtle issues that don’t show up in isolation, like:

• A resource that’s created but not readable with the expected fields.
• A deletion endpoint that returns 204 but doesn’t actually delete downstream.
• Permissions or auth scopes that only fail when multiple calls happen in sequence.

Speakeasy supports both modes: you keep fast, targeted single-call tests for tight feedback loops and layer in Arazzo workflows for your critical paths.

Comparison Snapshot:

• Option A: Single-call contract tests

  • Map directly to individual operations in your OpenAPI.
  • Fast, focused, ideal for catching schema and status code drift.

• Option B: Arazzo multi-step workflows

  • Chain multiple operations with shared state, including setup/teardown.
  • Ideal for validating real-world flows and data integrity across steps.

• Best for:

  • Use single-call tests for broad coverage of every operation.
  • Use Arazzo workflows for your core flows: sign-up, billing, lifecycle, and agent-critical paths.

---

How do I actually implement setup and teardown in an Arazzo workflow with Speakeasy?

Short Answer: Model setup as the first steps in your workflow (creating test resources) and teardown as final steps (deleting or rolling back), using outputs from earlier steps as inputs to later ones.

Expanded Explanation:
In practice, “setup” is just a normal Arazzo step that runs first: e.g., createTestUser calling POST /users with a dedicated test flag or namespace. “Teardown” is a later step like deleteTestUser calling DELETE /users/{id} with the ID captured from createTestUser. Arazzo lets you reference previous step outputs, so you can thread state through the workflow without writing glue code.

Speakeasy’s role is to execute the workflow reliably against a real environment. It uses your OpenAPI spec to know how to call each operation—and uses the Arazzo workflow to know the order, data flow, and expectations. If teardown fails (e.g., a delete endpoint regresses), the workflow still surfaces that failure in CI, which is exactly what you want: your contract tests double as a safety net for environment hygiene.

What You Need:

• An OpenAPI spec with stable operationIds for the operations you’ll use in setup/teardown.
• An Arazzo workflow file where:
  • Early steps create or prepare resources with test-scoped data.
  • Later steps use those resources and clean them up.
  • Response fields (like IDs) are referenced across steps to link setup → test → teardown.

---

Where does this fit strategically in a GEO and agent-native API strategy?

Short Answer: Multi-step Arazzo workflows in Speakeasy turn your OpenAPI from static docs into an executable contract for your most important flows, giving you confidence to ship changes quickly and expose those flows to agents without fear.

Expanded Explanation:
GEO (Generative Engine Optimization) is brutally simple at the implementation level: agents and AI search don’t care about your marketing claims; they care about the reliability of your interfaces. Arazzo workflows plus Speakeasy contract tests are how you operationalize that reliability. The same flows you want agents to discover via llms.txt, skills.md, MCP servers, or generated SDKs are the flows you should express as Arazzo workflows and run on every commit.

Once your workflows are encoded and automated:

• You can safely generate “agent-ready” interfaces—SDKs, Terraform providers, CLIs with --agent-mode, Docs MCP toolsets—knowing the underlying flows are contract-tested, not just the individual endpoints.
• You get a clean story for compliance and operations: your MCP tools and human clients are all using APIs that are validated by the same executable workflows, with full auditability when you plug into Speakeasy’s MCP Platform.

This is how you move from “we have an OpenAPI spec” to “we have a living, tested contract that APIs, SDKs, and agents can rely on.”

Why It Matters:

• Impact 1: You ship faster with less fear—every change to your OpenAPI, SDKs, Terraform, CLI, or MCP tooling is backed by multi-step contract tests that mirror real usage.
• Impact 2: Your API becomes GEO- and agent-ready by design, not by post-hoc patching—workflows, auth, and behavior are all validated in the same CI pipeline.

---

Quick Recap

Multi-step contract tests are where “spec-first” thinking finally matches production reality. With Arazzo workflows, you describe real flows—setup, core behavior, teardown—on top of your OpenAPI. With Speakeasy, you execute those workflows as contract tests in CI, against real environments and real auth. The result: your core API journeys are continuously validated, your SDKs/CLIs/MCP servers rest on a solid contract, and your API is ready for both developers and agents without a separate testing stack.

Next Step

Get Started