API workflow testing with Arazzo specs and Specmatic: Visual authoring, workflow mocking, and testing

This content originally appeared on DEV Community and was authored by digitalvoice-nz

Introduction
Why workflow mocking matters
Visual authoring of Arazzo API specifications
Generating the Arazzo YAML and data models
Running a workflow mock for front-end isolation
Switching from mock to API workflow testing for back-end services
How Specmatic discovers service endpoints from Arazzo specs
Best practices and tips for API workflow testing
Conclusion
FAQ

Introduction

In this demonstration we walk through how to author an Arazzo API specification visually with Specmatic and then leverage that specification to both mock complex multi-service workflows and run comprehensive API workflow testing, whether you are building a front end in isolation or validating a set of backend services together.

The pattern is simple but powerful: define a single workflow that describes the sequence of API calls across services, generate a validated Arazzo (OpenAPI-style) YAML, spin up a coordinated workflow mock so your front end can work without real back ends, and then flip to API workflow testing to validate the actual back-end services and their interactions. This approach gives you deterministic development, fast feedback, and high confidence in cross-service behaviors.

Why workflow mocking matters

Modern applications rarely rely on a single backend. Instead, front ends often orchestrate multiple services in sequence: authenticate a user, fetch location or profile data, query product availability, and finally place an order. These are not independent API calls—they form a user journey where responses must be coordinated. This is where workflow mocking and API workflow testing shine.

Workflow mocking is critical for several reasons:

Front-end independence: Developers and UX designers can build and iterate UI features without waiting for incomplete or volatile backend implementations.
Deterministic scenarios: Mocks can provide predictable responses for happy paths and edge cases, enabling deterministic testing and reproducible bugs.
Integrated journeys: Rather than mocking isolated endpoints, a workflow mock coordinates multiple endpoint responses so that the entire flow behaves as expected.

When you combine a formally authored Arazzo API specification with a tool like Specmatic, you have a single source of truth that can drive both your mocks and your tests.

Visual authoring of Arazzo API specifications

Authoring an Arazzo spec by hand is possible, but tedious and error-prone. A visual authoring experience accelerates the process and reduces mistakes. Using a canvas, you drag and drop operations to form a workflow: for example, first call the user location service, next call the product service for that location, then call the order service to create the order.

The key benefits of visual authoring are:

Immediate feedback on sequencing and branching logic
Automatic generation of success criteria and alternative paths
Automatic creation of the corresponding Arazzo YAML and data models

In the demo workflow you can see three steps connected visually. Specmatic analyzes the operations and infers where branching is necessary: a 2xx response from the user details API lets the journey continue, while a non-2xx response immediately terminates that path. This automated discovery of success criteria saves time and prevents subtle logical errors in workflow definitions.

Generating the Arazzo YAML and data models

Once the workflow canvas looks right, you generate the Arazzo YAML (an OpenAPI-style specification adapted for Arazzo). Specmatic will produce a standards-compliant YAML file that includes:

Paths and operations for each service
Request/response schemas
Server definitions (URLs for each service)
Example data and stub datasets that the mock can use

The generated YAML is accurate because it is derived directly from the visual model and is validated against the Arazzo/OpenAPI grammar. You avoid manual YAML editing errors and ensure the spec matches the intended workflow.

Alongside the YAML, Specmatic generates sample data and contexts. These data models are not throwaway examples; they become the inputs used by the workflow mock and by the API workflow testing step.

Running a workflow mock for front-end isolation

With the YAML and data models in place, spinning up a workflow mock is a single click. The workflow mock runs as a coordinated set of endpoint stubs: when the front end hits /login or /getLocation, the mock returns staged responses consistent with the workflow context.

Why coordinated mocks are valuable:

The front end can run through multi-step flows without touching real services.
Mocked responses can be context-aware so that data returned by step 1 affects step 2.
You can test both happy and unhappy paths by switching contexts (for example, a location that has products vs. a location with no products).

In the example walkthrough, the mock provided two journeys: the default happy path (user Truman logs in, location resolves, products are available, order placed) and a not-so-happy path (a different user logs in, location resolves but no products are available, so the flow stops).

Practically, here’s how to use the mock during front-end development:

Start the workflow mock in Specmatic.
Launch the front-end app, pointed at the mock’s base URL.
Use the generated dataset values (e.g., sample emails and passwords) that came with the Arazzo YAML to exercise different scenarios.
Switch input contexts in the mock to test alternate flows like absence of products or server errors.

The mock tab also tracks which API calls were covered in a session, so you can immediately see which endpoints and flows have been exercised. This coverage view is useful to validate your front-end test cases and ensure the mock behavior aligns with the UI expectations.

Switching from mock to API workflow testing for backend services

Once the front end is stable against the mock, the next step is to validate the real backend services together with an API workflow testing run. API workflow testing is not just unit tests of individual endpoints—it executes the same workflow sequence across actual services to ensure the overall journey behaves as expected.

Key differences between mocking and API workflow testing:

Mocking isolates the front end by answering calls itself. API workflow testing executes calls against actual services.
The mock returns deterministic stub data. API workflow testing must align its inputs with the real services’ data (databases, initial state).
API workflow testing validates cross-service integration and end-to-end behavior.

The transition is straightforward:

Stop the workflow mock in Specmatic.
Switch the Specmatic environment from “mock” to “test” (the QS switch in the demo).
Bring up the real services locally (in the demo, the location and order services were started).
Load or specify the input data that matches the services’ databases, using the Arazzo YAML to validate inputs against schemas.
Run the API workflow test and inspect the coverage and flowchart results.

When running an API workflow test, Specmatic walks through the workflow, making real HTTP calls to the configured service endpoints. It then reports:

Workflow coverage percentage
The path(s) that were executed (happy path or alternative paths)
Detailed request/response logs for every operation

In the demo, the test reported 100% API workflow coverage for the selected contexts. You could visually see the flowchart and pick contexts to review alternate journeys: the happy path where products existed and the not-so-happy path where no products existed, and therefore no order was placed.

How Specmatic discovers service endpoints from Arazzo specs

A common question is: how does Specmatic know which server URL to call for each service when running API workflow testing? The answer is simple and elegant: the Arazzo YAML itself contains server definitions for each API specification.

When Specmatic generates or loads the Arazzo spec, it reads the “servers” or “service” section where each service URL is declared. This allows Specmatic to map operations to concrete endpoints without any additional configuration. This mapping is essential for multi-service workflows because each operation could belong to a different service and therefore a different base URL.

Because the Arazzo spec contains the server URLs (e.g., http://localhost:3000 for the order service), Specmatic automatically calls the right server for each operation during testing. This eliminates boilerplate configuration and ensures the single source of truth—the Arazzo spec—governs both the mock and the test behavior.

Best practices and tips for API workflow testing

Based on the demo and common patterns, here are practical recommendations to make API workflow testing more effective:

1. Author the Arazzo spec first, iterate visually

Start with the workflow canvas and identify the operations and their order. Visual iteration makes it easy to spot missing branches, identify success and failure criteria, and capture all user journeys before translating them into tests.

2. Model contexts for different journeys

Create named contexts like “happy-path”, “no-products”, “auth-failure”. These contexts allow both the workflow mock and the API workflow testing to switch semantics quickly and reproducibly.

3. Keep test data aligned with real services

For API workflow testing, make sure your input data matches what your services expect. Use the generated sample datasets as a starting point, but ensure the database state for your local services is consistent (migrations, seed data, etc.). Specmatic validates inputs against the Arazzo schemas to help catch mismatches early.

4. Use coverage and visual flow reports to find gaps

The flowchart and coverage metrics show which branches of your workflow are exercised. If a path is untested, either add a new test context or expand your mock scenarios. These visual artifacts are invaluable for both development and QA.

5. Integrate API workflow testing into CI pipelines

Once your tests are stable, run them as part of CI to validate every commit. Because the Arazzo spec contains service URLs, you can orchestrate ephemeral test environments and run the same workflow tests reliably in CI.

6. Document the workflow and contexts

Keep the workflow canvas and Arazzo YAML alongside developer docs so team members understand which journeys exist and what contexts they can use.

These practices will make your API workflow testing robust, repeatable, and valuable to the entire delivery pipeline.

Conclusion

Workflow mocking and API workflow testing are two sides of the same coin. By authoring a clear Arazzo spec visually, you gain a reliable single source of truth that can drive both:

Coordinated workflow mocks for front-end development and manual testing
Comprehensive API workflow testing that validates cross-service behavior in real environments

Specmatic makes it possible to go from a visual workflow to a standards-compliant Arazzo YAML, then to a running mock, and finally to thorough API workflow testing. That smooth progression reduces friction between frontend and backend teams and increases confidence in deployed behavior.

If you want predictable front-end development and high-quality integration tests, adopting a visual-first approach to authoring Arazzo specs and leveraging tools that support both mocking and testing is a practical, high-impact strategy.

FAQ

What is the difference between a workflow mock and an API workflow test?

A workflow mock returns deterministic stubbed responses locally to simulate backend behavior so the front end can work independently. An API workflow test executes the same workflow but makes real calls to actual services to validate integration and end-to-end behavior.

Do I need an Arazzo spec to use Specmatic?

Specmatic works best when you have an Arazzo specification because the spec provides structured definitions of paths, schemas, and server endpoints. Visual authoring in Specmatic will generate a correct Arazzo YAML for you, so you can start visually instead of writing the spec manually.

How do I handle database state for API workflow testing?

For API workflow testing, ensure your services are seeded with known test data that matches the inputs you provide. Use the example datasets generated with the Arazzo YAML as a reference, and create local seeds or fixtures that align with those values. Specmatic validates inputs against schemas to help catch mismatches.

Can I run API workflow testing in CI?

Yes. Because the Arazzo spec includes server URLs, you can configure CI to start ephemeral service instances, run migrations/seeds, and then execute Specmatic workflow tests as part of your pipeline.

How do I test error cases and alternative paths?

Create contexts in your Arazzo spec and in Specmatic for alternative scenarios: authentication failures, resource not found, empty product arrays, etc. Use those contexts in the workflow mock and in tests to exercise error handling and alternative flows.

How does Specmatic determine which service to call during API workflow testing?

Specmatic reads the server definitions in the Arazzo YAML. Each operation in the spec is associated with a service, and the server URL for that service tells Specmatic where to execute the call. This removes manual wiring of service endpoints.

What are good practices for keeping specs and tests in sync?

Keep the Arazzo spec as the source of truth. Whenever APIs change, update the spec first, then regenerate mocks and tests. Use version control for specs and job hooks (pre-commit or CI checks) to validate that specs and tests remain compatible.

Final notes

If you’re exploring ways to bring more structure to front-end/back-end integration and to reduce the friction of multi-service development, a visual-first Arazzo spec plus coordinated workflow mocking and API workflow testing is a strategy worth adopting. It shortens feedback loops, clarifies intended behavior across teams, and makes integration bugs far easier to diagnose.

The combination of visual authoring, Arazzo specs, Specmatic-driven mocks, and API workflow testing provides a clean, repeatable path from design to validated implementation.

Note: Throughout this article we referred to the central process as API workflow testing and demonstrated how a visual Arazzo-first approach, combined with Specmatic, enables reliable mocks and tests across multi-service journeys.