Arazzo

Introduction

Specmatic-Arazzo facilitates the generation of workflows, testing, mocking, and additional functionalities by utilizing the industry-standard Arazzo Specification

Specmatic-Arazzo stands out as the only tool that currently supports orchestrating complete workflows with event-driven steps powered by AsyncAPI

What Can You Achieve with Specmatic’s Arazzo Support?

  • Workflow Generation: Specmatic Arazzo enables you to create Arazzo workflows interactively via Specmatic Studio or programmatically through the Command Line Interface.

  • Workflow Validation: Specmatic Arazzo validates your Arazzo specifications not only against the Arazzo Specification schema but also checks your payloads, parameters, and references against the definitions in your Arazzo specification. It can also perform closed-loop testing using the specification.

  • Workflow Testing: Specmatic Arazzo executes the workflows defined in your Arazzo specification, covering both happy and unhappy paths. It provides a textual report in the console and an interactive HTML report for further analysis, allowing you to drill down into specific test cases if needed.

  • Workflow Mocking: Specmatic Arazzo can initiate a mock server using your Arazzo specification and input data. The mock server can replicate the individual workflows and steps according to the mock data and previous requests/responses.

Generating Workflows

Workflows can be generated in two ways using Specmatic-Arazzo, either interactively through Specmatic Studio or programmatically via the Command Line Interface using the Docker image specmatic/specmatic-arazzo

Interactive through Specmatic Studio

In the interactive approach, you can import your API specifications into Specmatic Studio and utilize a drag-and-drop interface to visually design workflows. Each workflow can be built by connecting operations from your specifications in the intended sequence to represent a business flow

Take a look at the Microservices with Event-Driven Architecture Sample to observe its functionality

Command Line Interface

In the CLI-based method, workflows can be created programmatically by manually writing a minimal Arazzo specification and executing the specmatic arazzo generate command.

The minimal specification should consist of the arazzo object along with the sourceDescriptions array and steps that include either operationId or operationRef

All other components, such as parameters, requestBody, successCriteria, and onSuccess/onFailure actions, are generated automatically

Refer to the Microservices Sample for practical implementation details

Understanding Generated Files

When you generate workflows using Specmatic-Arazzo, two files will be created. Both files share the same prefix name to maintain their linkage as a pair:

  • *.arazzo.yaml — Contains the Arazzo workflow specification (e.g. PlaceOrder.arazzo.yaml)
  • *.arazzo_inputs.json - Contains the input data for the workflow (e.g. PlaceOrder.arazzo_inputs.json)

Arazzo Workflow Specification (*.arazzo.yaml)

This file is the standard Arazzo workflow specification, detailing the flow of operations, references to API specifications, and the connections between each step. It encapsulates the logic of the workflow, including the “what” and the “how.”

Arazzo Input Data (*.arazzo_inputs.json)

This file contains the input data required for executing the workflow. It specifies values for parameters, request bodies, or variables needed throughout the workflow. The format is as follows:

{
    "PlaceOrder": {
        "DEFAULT": {
            "PlaceOrder": {
                "orderRequestId": "1234567890"
            },
            "GetUserDetails": {
                "email": "[email protected]",
                "password": "specmatic",
                "internalToken": "API-TOKEN"
            }
        },
        "GetProducts.IsArrayEmpty": {
            "$failureMessage": "Expected not to find any products for [email protected], as they belong to B Zone",
            "GetUserDetails": {
                "email": "[email protected]",
                "password": "user"
            }
        }
    }
}

Understanding the Structure

  • PlaceOrder → Represents the name of the workflow.
  • DEFAULT → Contains the default scenario with all necessary input data for the workflow.
  • GetProducts.IsArrayEmpty → A specific scenario indicating that the GetProducts step and its action IsArrayEmpty should evaluate to true.

This input file triggers two workflow test runs:

  • One for the DEFAULT scenario.
  • Another for the GetProducts.IsArrayEmpty scenario.

Scenario Behavior

  • $failureMessage (optional): Displays a custom message if the scenario does not evaluate to true as expected.
  • The DEFAULT scenario must include all required inputs for convenience and completeness.
  • Partial Scenarios: Non-default scenarios (like GetProducts.IsArrayEmpty) can specify only the fields they need to override, which will automatically merge with the data from the DEFAULT scenario.

Running Workflow Tests

After creating a workflow, you can execute tests on your microservices to validate the entire end-to-end flow. Testing can be performed either interactively through Specmatic Studio or via the Command Line Interface using the Docker image, In either case at the end of the workflow mock, an HTML report will be generated to provide a visual representation of interactions in ./build/reports/specmatic/html

Interactively through Specmatic Studio

In Specmatic Studio, it is possible to execute workflow tests directly via the visual interface. The Studio offers an intuitive method for selecting which specification will run against which base URL, utilizing a drop-down menu that automatically pulls options from the servers section of your specifications.

During the test execution, Studio also enables you to:

  • Monitor real-time results
  • Visualize workflow execution through real-time flow diagrams
  • Debug and inspect responses and interactions between connected APIs as they occur

Command Line Interface

You can run workflow tests programmatically using the CLI with the test command from the Specmatic-Arazzo Docker image.

docker run -v "$(pwd):/usr/src/app" specmatic/specmatic-arazzo test "<workflow.arazzo.yaml>"

There are several methods to specify service URLs for your APIs via the CLI:

1. Utilize --serverUrlIndex and --serverUrlName:

For OpenAPI specifications, use --serverUrlIndex N to instruct Specmatic to select the N-th server URL from each OpenAPI specification.

For AsyncAPI specifications, use --serverUrlName NAME to direct Specmatic to choose the server URL with the specified name from each AsyncAPI specification.

2. Fine-Grained Control via System Properties:

You can override service URLs for specific specifications outlined in your Arazzo file by using system properties based on their names. For instance:

sourceDescriptions:
- name: "LocationApi"
  url: "./workflow/openapi/location.yaml"
  type: "openapi"
- name: "OrderApi"
  url: "./workflow/asyncapi/order.yaml"
  type: "asyncapi"

Assign specific URLs for each specification with the following system properties:

LocationApi=http://localhost:8081; OrderApi=http://localhost:8082

3. Fallback Host and Port:

You can set a default fallback host and port using --host <host> --port <port> in the test command. These values will serve as a last resort if no other URL configurations match.

Workflow Mocking

After generating a workflow, you can also use it to mock your Arazzo specification, allowing you to simulate the workflow itself, not just the underlying services. When a workflow is mocked, Specmatic tracks which step has been executed, what comes next, and what response should be returned, based on your workflow definition and its input file.

Just like workflow testing, mocking can be performed either interactively through Specmatic Studio or via the Command Line Interface using the Docker image, In either case at the end of the workflow mock, an HTML report will be generated to provide a visual representation of interactions in ./build/reports/specmatic/html

Interactively through Specmatic Studio

In Specmatic Studio, you can start a mock workflow session to simulate end-to-end behavior without running your actual services, Studio uses the workflow definition to:

  • Monitor real-time request / responses
  • Visualize workflow execution through real-time flow diagrams
  • Debug and inspect interactions as they occur

Command Line Interface

You can also run workflow mocking through the CLI using the mock command from the Specmatic-Arazzo Docker image:

docker run -v "$(pwd):/usr/src/app" specmatic/specmatic-arazzo mock --spec-file "<workflow.arazzo.yaml>"

Sample Projects

Here are several sample projects you can explore to begin working with Specmatic-Arazzo. Each project includes detailed instructions in its respective README file, along with a video walkthrough that covers everything from generating an Arazzo specification to testing and mocking workflows using Specmatic-Arazzo.