# `Cuerdo`

Cuerdo is an [Arazzo](https://spec.openapis.org/arazzo/v1.1.0) workflow runner and automatic property-based testing tool written in Elixir.

Arazzo is a community-driven specification within the OpenAPI Initiative, a project part of the
Linux Foundation Collaborative.
OpenAPI describes REST APIs, and Arazzo specifies how to combine multiple individual OpenAPI
endpoints as a "workflow". Workflows consist of one or more steps, where each step consists of
either an HTTP request referencing an OpenAPI endpoint, or another workflow. For more information,
refer to the [Arazzo official site](https://www.openapis.org/arazzo-specification).

One of Cuerdo's primary goals is reducing the amount of hand-written integration tests
required to validate API workflows.
When used with `Cuerdo.ArazzoCase`, workflow inputs are automatically generated from the
JSON Schemas defined in the Arazzo document.
Each workflow is then executed multiple times with different generated inputs.

In addition to evaluating Arazzo successCriteria, Cuerdo validates that requests and responses
conform to the OpenAPI contract associated with each operation.
This includes schema validation, content type validation, required parameter checks,
and response status code verification.

As a result, a single Arazzo document can serve both as executable workflow documentation
and as a property-based test suite.

## Quick Start
Define a [`arazzo_document_test`](`Cuerdo.ArazzoCase.arazzo_document_test/1`) in your test module
```elixir
defmodule MyTest do
  use Cuerdo.ArazzoCase

  arazzo_document_test document: YamlElixir.read_from_file!("arazzo.yaml")
end
```

Or execute a workflow directly
```elixir
iex> inputs = %{"email" => "user@example.com", "password" => "securePassword"}
iex> document = YamlElixir.read_from_file!("arazzo.yaml")
iex> {:ok, context} = Cuerdo.Arazzo.run_workflow(inputs, "createUserWorkflow", document)
iex> Cuerdo.Arazzo.Context.workflow_outputs(context, "createUserWorkflow")
%{"token" => "userSessionToken"}
```

## Usage
Consider the following simple workflow. A single GET request with query parameters that queries
"people" entities, and validates that the returned object matches the input filters

```yaml
# specs/arazzo.yaml
- workflowId: getPeople
  inputs:
    type: object
    additionalProperties: false
    required: ["name"]
    properties:
      name:
        type: string
        minLength: 1
  steps:
    - stepId: getPeopleStep
      operationId: getPeople
      parameters:
        - name: name
          in: query
          value: $inputs.name
      successCriteria:
        - condition: $statusCode == 200
        - type: regex
          context: $response.body#/0/name
          condition: "^$inputs.name"
      outputs:
        firstMatchingName: $response.body#/0/name
  ```

### Directly in code
You can run the workflow directly with specific inputs via `Cuerdo.Arazzo.run_workflow/3`, for
example

```elixir
inputs = %{"name" => "John"}
arazzo_document = YamlElixir.read_from_file!("path/to/arazzo.yaml")
{:ok, context} = Cuerdo.Arazzo.run_workflow(inputs, "getPeople", arazzo_document)
```

On success, the function returns a `t:Cuerdo.Arazzo.Context.t/0` containing workflow outputs,
step outputs, and request/response data for each executed step.

```elixir
iex> Cuerdo.Arazzo.Context.step_outputs(context, "getPeople", "getPeopleStep")
%{"firstMatchingName" => "Johnathan"}
```

### ArazzoCase
You can execute the workflow(s) as part of a test suite, using `Cuerdo.ArazzoCase`.
Consider the same Arazzo workflow from [above](#module-usage), you can define a test module
as follows
```elixir
# test/myapp/get_people_test.exs
defmodule MyApp.GetPeopleTest do
  use Cuerdo.ArazzoCase

  arazzo_document_test document: YamlElixir.read_from_file!("path/to/arazzo.yaml")
end
```
The `Cuerdo.ArazzoCase.arazzo_document_test/1` macro generates a test for each workflow with random
inputs generated by `RockSolid.from_schema/2`. To exclude specific workflows, apply transformation
functions, and other options refer to [arazzo_document_test](`Cuerdo.ArazzoCase.arazzo_document_test/1`)

## Validations
On top of the validations defined by `successCriteria` field, the following non-Arazzo validations
are performed at every step:
- The workflow inptus match the `inputs` schema in the Arazzo document
- The request Content-Type header matches any of the Content-Type defined in the OpenAPI operation
- The request body matches the schema defined in the OpenAPI operation
- All required parameters defined in the OpenAPI operation are present in the step definition
- The response body matches any of the schemas defined in the OpenAPI operation based on the
Content-Type response header and response status code

---

*Consult [api-reference.md](api-reference.md) for complete listing*