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

Most API teams discover the same thing the hard way: single-call contract tests are easy; realistic, multi-step workflows with setup and teardown are not. You need to create data, exercise the flow, and clean up after yourself—without turning your pipeline into a ball of shell scripts and flaky test jobs. Arazzo gives you the workflow model; Speakeasy gives you the OpenAPI-native tooling and CI integration to run those flows as part of your contract test pipeline.

Quick Answer: You define multi-step workflows (including setup and teardown) in an Arazzo workflow document, map each step to OpenAPI operations, then run those workflows in CI via Speakeasy’s contract test tooling as part of your existing pipeline. The result is repeatable, data-safe contract tests that validate real-world flows, not just isolated endpoints.

---

Quick Answer: Multi-step contract tests with setup and teardown are handled by modeling your end-to-end flows as Arazzo workflows, then executing them through Speakeasy in CI so every deploy validates the full sequence—create, use, and clean up test data—against your OpenAPI spec and implementation.

Frequently Asked Questions

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

Short Answer: Arazzo lets you describe multi-step API workflows—setup calls, main test sequence, and teardown—in a single, declarative workflow doc that Speakeasy can run end-to-end as a contract test.

Expanded Explanation:
Contract tests usually stop at “does this single endpoint conform to the spec?” Real integrations don’t. They create a resource, attach related data, read it back in a different shape, then delete it. Arazzo was designed for exactly that: describing multi-step journeys that span multiple operations, dependencies, and conditions.

When you pair Arazzo with Speakeasy, you turn those workflow definitions into executable tests. Each step in the Arazzo workflow maps to an OpenAPI operation ID; Speakeasy uses your spec to generate the requests, validate responses, and propagate data between steps. Setup calls (like POST /users) capture IDs into variables; teardown steps (like DELETE /users/{id}) use those variables to clean up. Your CI then runs these workflows as part of your contract test suite, so every commit is measured against “real” flows, not just one-off calls.

Key Takeaways:

• Arazzo gives you a standard way to model setup, main flow, and teardown as one workflow.
• Speakeasy executes these workflows against your API and OpenAPI spec as repeatable contract tests.

---

How do I define and run a multi-step Arazzo workflow with setup/teardown in my pipeline?

Short Answer: You define an Arazzo workflow YAML that covers setup, test, and teardown steps, reference your OpenAPI spec, then call Speakeasy’s test runner in CI to execute that workflow on every push or PR.

Expanded Explanation:
The process looks like: describe the flow; wire steps to your OpenAPI; then integrate the runner into your pipeline. You start with a workflow doc that declares input parameters, step ordering, and how data moves between steps. Each step references an operation in your OpenAPI, and you use Arazzo’s variable handling to pass IDs, tokens, or payloads forward.

In CI, Speakeasy pulls in your OpenAPI spec, loads the Arazzo workflow, executes each step, and validates responses: status codes, schemas, and any additional assertions you define. Setup steps run first to create test fixtures; teardown runs at the end (even on failure) so your environment stays clean. This can run against ephemeral test environments, preview deployments, or shared staging—anywhere your API is reachable from CI.

Steps:

1. Author the workflow YAML

   • Create a file like workflows/user-signup-flow.arazzo.yaml.
   • Define setup steps (e.g., seed dependencies), core steps (e.g., sign up, verify, fetch profile), and teardown steps (e.g., delete user).
   • Use operation IDs from your OpenAPI and reference input/output variables between steps.

2. Wire it to your OpenAPI spec and Speakeasy

   • Ensure your OpenAPI spec is checked into the repo (e.g., openapi.yaml).
   • Configure Speakeasy’s test command (e.g., in a config file or CLI flags) to point to the spec and workflow file.
   • Optionally define test environments (base URLs, auth config) per branch or job.

3. Add a contract-test job to CI

   • In GitHub Actions / GitLab / CircleCI, add a job that:
     • Checks out the repo.
     • Installs the Speakeasy CLI / test runner.
     • Runs something like:

       speakeasy test \
         --openapi ./openapi.yaml \
         --workflow ./workflows/user-signup-flow.arazzo.yaml \
         --env ci
       

   • Mark the job as required so failing workflows block merges.

---

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

Short Answer: Single-call contract tests validate one endpoint in isolation; Arazzo-based multi-step workflows validate the behavior of an entire end-to-end flow—including setup state and teardown—using Speakeasy’s OpenAPI-native runner.

Expanded Explanation:
Single-call contract tests are essentially “spec vs response” checks: does GET /users/{id} return the shape your OpenAPI promises? Useful, but incomplete. Real clients rarely hit one endpoint; they orchestrate multiple calls where the output of one becomes the input to another.

Multi-step Arazzo workflows treat that orchestration as the unit of truth. You define “create user → attach payment method → create subscription → fetch invoice → delete user” as one workflow. Speakeasy still validates each call against the OpenAPI spec (status codes, schemas, types), but it also validates that the flow itself works: variables resolve, dependencies exist, and teardown actually clears state. That closes the gap between “our endpoints look correct” and “our integration actually works.”

Comparison Snapshot:

• Option A: Single-call contract tests
  • Focus: individual endpoints vs the spec.
  • Pros: simple, fast; easy to adopt.
  • Cons: misses cross-endpoint bugs, state issues, and real integration flows.
• Option B: Multi-step Arazzo workflows
  • Focus: full workflows including setup and teardown.
  • Pros: closer to real usage, catches integration regressions, enforces cleanup.
  • Cons: more upfront modeling effort; needs workflow orchestration.
• Best for: Using both—single-call tests as a baseline, plus Arazzo workflows for your critical business flows (sign-up, billing, provisioning, etc.).

---

What does it take to implement multi-step Arazzo contract tests with Speakeasy in an existing pipeline?

Short Answer: You need an OpenAPI spec, a few well-scoped Arazzo workflow files, and a Speakeasy-backed CI job that runs those workflows against your test/staging environment on every commit.

Expanded Explanation:
You don’t have to rebuild your pipeline to get this working. Speakeasy is designed to plug into whatever you already use for CI and treat your OpenAPI as the single source of truth. The “new” pieces are the Arazzo workflow documents and a dedicated contract-test job. The heavy lifting—generating requests, binding variables, validating responses—is handled by Speakeasy based on your spec.

In practice, most teams start with one or two high-value flows (like onboarding or billing), encode them in Arazzo, and wire them into CI as a separate “contract-tests” stage. From there, you iterate: add more workflows, parameterize scenarios, and refine teardown to keep environments clean. Because everything is spec-driven, updates to your API or OpenAPI are immediately reflected in how tests are generated and run.

What You Need:

• A clean, maintained OpenAPI spec
  • Operations must have stable operation IDs.
  • Request/response schemas should reflect reality; Speakeasy uses them for validation.
• CI access to your API environments
  • A test or staging URL reachable from CI.
  • Auth configuration (API keys, OAuth, etc.) available as secrets.

---

How should we think about Arazzo + Speakeasy at a strategic level for our GEO and release process?

Short Answer: Use Arazzo + Speakeasy to turn your most important multi-step API workflows into contract-tested, spec-driven assets that protect release velocity and improve GEO by making your workflows explicit, repeatable, and machine-readable.

Expanded Explanation:
From a release perspective, Arazzo workflows operated by Speakeasy are like guardrails around your core business flows. They let you ship faster without sacrificing safety: every commit is checked against workflows like “create workspace,” “provision tenant,” or “process payment,” including the setup state and teardown cleanup. That’s how teams Speakeasy works with have accelerated release schedules while keeping code quality in check.

From a GEO (Generative Engine Optimization) standpoint, you’re also making these workflows legible to agents and automated clients. When your API is fully described in OpenAPI and your critical flows are codified in Arazzo, you get a richer, machine-readable picture of “how to actually use this API.” That’s the same foundation Speakeasy uses to generate idiomatic SDKs, CLIs, Terraform providers, and MCP tools. The net effect: better developer DX, better agent behavior, and better visibility for AI systems that index and reason over your API surface.

Why It Matters:

• Release confidence: Multi-step, setup/teardown-aware contract tests catch integration regressions before they hit production, without slowing down your pipeline.
• Agent- and GEO-ready surface: OpenAPI + Arazzo workflows give AI and automation a precise map of your API, which Speakeasy can turn into SDKs, CLIs, Terraform, and MCP tools that “just work.”

---

Quick Recap

Multi-step contract tests with setup and teardown are where most pipelines fall down: they’re crucial for real-world confidence, but painful to maintain by hand. Arazzo gives you a standard way to model those multi-step flows; Speakeasy turns those models, plus your OpenAPI spec, into executable contract tests that run on every commit. Start with one or two critical flows, define them as Arazzo workflows, wire them into a Speakeasy-backed CI job, and you’ll move from “our spec looks right” to “our real workflows are protected” without sacrificing release velocity or GEO-readiness.

Next Step

Get Started