setup-sdk-testing

Files (2)

• SKILL.md
• arazzo-reference.md · content/

SKILL.md (first lines)

# setup-sdk-testing

Set up and run tests for Speakeasy-generated SDKs using contract testing, custom Arazzo workflows, or integration tests against live APIs.

## Content Guides

| Topic | Guide |
|-------|-------|
| Arazzo Reference | [content/arazzo-reference.md](content/arazzo-reference.md) |

The Arazzo reference provides complete syntax for workflows, steps, success criteria, environment variables, and chaining operations.

## When to Use

- Setting up automated testing for a generated SDK
- Enabling contract test generation via `gen.yaml`
- Writing custom multi-step API workflow tests with Arazzo
- Configuring integration tests against a live API
- Debugging `ResponseValidationError` or test failures
- User says: "test SDK", "contract testing", "Arazzo tests", "speakeasy test", "mock server", "test generation"

## Inputs

| Input | Required | Description |
|-------|----------|-------------|
| `gen.yaml` | Yes | Generation config; contract testing is enabled here |
| OpenAPI spec | Yes | The API spec the SDK is generated from |
| Target language | Yes | `typescript`, `python`, `go`, or `java` (contract test support) |
| `.speakeasy/tests.arazzo.yaml` | No | Custom Arazzo test definitions |
| Live API credentials | No | Required only for integration testing |

## Outputs

| Output | Location |
|--------|----------|
| Generated contract tests | `tests/` directory in SDK output |
| Mock server config | Auto-generated alongside contract tests |
| Arazzo test results | Terminal output from `speakeasy test` |
| CI workflow | `.github/workflows/` (if integration testing configured) |

## Prerequisites

- Speakeasy CLI installed and authenticated (`speakeasy auth login`)
- A working SDK generation setup (`gen.yaml` + OpenAPI spec)
- For integration tests: API credentials as environment variables

## Decision Framework

Pick the right testing approach based on what you need:

| Need | Approach | Effort |
|------|----------|--------|
| Verify SDK types and methods match the API contract | Contract testing | Low (auto-generated) |
| Test multi-step API workflows (create then verify) | Custom Arazzo tests | Medium |
| Validate against a live API with real data | Integration testing | High |
| Catch regressions on every SDK regeneration | Contract testing + CI | Low |
| Test authentication flows end-to-end | Integration testing | High |
| Verify chained operations with data dependencies | Custom Arazzo tests | Medium |

**Start with contract testing.** It is auto-generated and catches the most common issues. Add custom Arazzo tests for workflow coverage, and integration tests only when live API validation is required.

## Command

### Enable Contract Testing

Add to `gen.yaml`:

```yaml
generation:
  tests:
    generateTests: true
```

Then regenerate the SDK:

```bash
speakeasy run --output console
```

### Run Tests

```bash
# Run all Arazzo-defined tests (contract + custom)
speakeasy test

# Run tests for a specific target
speakeasy test --target my-typescript-sdk

# Run with verbose output for debugging
speakeasy test --verbose
```

### Run via CI

Contract tests run automatically in the Speakeasy GitHub Actions workflow when test generation is enabled. No additional CI configuration is needed for contract tests.

## Example

### 1. Contract Testing (Quick Start)

Enable test generation in `gen.yaml`:

```yaml
generation:
  tests:
    generateTests: true
```

Regenerate the SDK:

```bash
speakeasy run --output console
```

Run the generated tests:

```bash
speakeasy test
```

From speakeasy-api/sdk-generation-skills, Apache-2.0.

More from speakeasy-api/sdk-generation-skills