Testing in GitHub Actions

Automatically run Speakeasy contract testing during pull requests or other events to a GitHub repository via GitHub Actions. Typically, this will be the repository containing the SDK and where SDK generation pull requests occur, however there are no limitations for more advanced setups.

There are two methodologies for running Speakeasy testing in GitHub Actions depending on your use case:

Within the existing Speakeasy generation GitHub Actions workflow: Easiest setup, however testing failures will prevent updates.
As a separate GitHub Actions workflow: More advanced setup, however testing failures will not prevent updates unless configured as a required pull request check in GitHub.

Prerequisities

TIP

If not previously completed as part of the SDK generation setup, the speakeasy configure github command automates and outputs useful information for the Speakeasy setup with GitHub.

The following are requirements for running Speakeasy testing in GitHub Actions:

GitHub repository with Actions enabled
GitHub Actions secret with Speakeasy API Key

Within Generation GitHub Actions Workflow

Enable the existing Speakeasy generation GitHub Actions workflow (typically .github/workflows/sdk_generation.yaml) to run testing as part of generation by modifying the Speakeasy workflow configuration.

Caveats

The following are known caveats for running Speakeasy testing as a part of the existing generation workflow in GitHub Actions:

Enabling the workflow configuration will also affect local speakeasy run CLI commands. Use the --skip-testing flag to explicitly skip testing with that command.

Enable Testing in Workflow Configuration

Modify the Speakeasy configuration file (.speakeasy/workflow.yaml) to enable testing to run as a part of the existing generation workflow in GitHub Actions.

Enable running tests during Speakeasy workflows by adding to one or more of the target configurations in the targets section of the configuration.

Enable testing for the target.

workflow.yaml

targets:
  example-target:
    # ... other existing configuration ...
    testing:
      enabled: true

Separate Testing GitHub Actions Workflow

Refer to the Workflow Syntax for GitHub Actions (opens in a new tab) documentation for additional information about the configurations shown and further customization options.

Caveats

The following are known caveats for running Speakeasy testing as a separate workflow in GitHub Actions:

It is not recommended to create a separate testing GitHub Actions workflow if the SDK generation action workflow (typically .github/workflows/sdk_generation.yaml) is configured with mode: direct or mode: test.
It is not recommended to add testing to the existing GitHub Actions workflow for the SDK generation action workflow (typically .github/workflows/sdk_generation.yaml). For example, it is not possible to add run: speakeasy test in the same job.
GitHub prevents any automatic workflow token (secrets.GITHUB_TOKEN) from automatically triggering other GitHub Actions workflows. By default, the SDK generation action workflow (typically .github/workflows/sdk_generation.yaml) is configured using an automatic workflow token, which means that any other GitHub Actions workflow such as this Speakeasy testing workflow will not automatically run for SDK generation pull requests. To workaround this limitation, choose either:
- Pass an externally created GitHub token, such as a personal access token, to the SDK generation workflow. This will enable other workflows to run automatically without intervention.
- Manually close and reopen SDK generation pull requests. Since the pull request actions are being done by a user, pull request workflows will run normally.

Single Language Testing

Create a .github/workflows/speakeasy-testing.yml file with the relevant language contents:

name: Speakeasy Testing
on:
  pull_request:
  push:
    branches:
      - main
permissions:
  contents: read
jobs:
  TypeScript:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version-file: "package.json"
      - run: curl -fsSL https://go.speakeasy.com/cli-install.sh | sh
      - run: speakeasy test
        env:
          SPEAKEASY_API_KEY: ${{ secrets.SPEAKEASY_API_KEY }}

name: Speakeasy Testing
on:
  pull_request:
  push:
    branches:
      - main
permissions:
  contents: read
jobs:
  Python:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.8"
      - run: pipx install "poetry~=1.8"
      - run: poetry install
      - run: curl -fsSL https://go.speakeasy.com/cli-install.sh | sh
      - run: speakeasy test
        env:
          SPEAKEASY_API_KEY: ${{ secrets.SPEAKEASY_API_KEY }}

name: Speakeasy Testing
on:
  pull_request:
  push:
    branches:
      - main
permissions:
  contents: read
jobs:
  Go:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version-file: "go.mod"
      - run: curl -fsSL https://go.speakeasy.com/cli-install.sh | sh
      - run: speakeasy test
        env:
          SPEAKEASY_API_KEY: ${{ secrets.SPEAKEASY_API_KEY }}

Multiple Language Testing

If your Speakeasy workflow includes multiple languages, choose a preferred style:

Single testing job: Returns a single status check for all languages. Add installation steps (e.g. uses: actions/setup-go) from each single language testing configuration prior to the speakeasy test command step. By default the speakeasy test command will run all workflow targets.
Multiple testing jobs: Returns status checks for each language and runs concurrently. Add the full job configuration from each single language testing configuration. Use different speakeasy test --target command flag values in each job to run individual workflow target tests. Refer to the Speakeasy workflow configuration (typically .speakeasy/workflow.yaml) for target names.

In this example, a Speakeasy workflow configuration has two targets named go-sdk and typescript-sdk:

targets:
  go-sdk:
    target: go
    # ... other configuration ...
  typescript-sdk:
    target: typescript
    # ... other configuration ...

From that example Speakeasy workflow configuration, multiple testing jobs are created for the targets:

name: Speakeasy Testing
on:
  pull_request:
  push:
    branches:
      - main
permissions:
  contents: read
jobs:
  Go:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version-file: "go.mod"
      - run: curl -fsSL https://go.speakeasy.com/cli-install.sh | sh
      - run: speakeasy test --target 'go-sdk'
        env:
          SPEAKEASY_API_KEY: ${{ secrets.SPEAKEASY_API_KEY }}
  TypeScript:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version-file: "package.json"
      - run: curl -fsSL https://go.speakeasy.com/cli-install.sh | sh
      - run: speakeasy test --target 'typescript-sdk'
        env:
          SPEAKEASY_API_KEY: ${{ secrets.SPEAKEASY_API_KEY }}

Next Steps

Advanced test configuration for your tests.