DDEV add-on test action

---

A GitHub action to run tests on a DDEV add-on.

---

Table of Contents

• Quick start
• Inputs
  • Available keys
• Usage
  • Test your DDEV add-on
    • bats tags and the test_command input
• License
• Contribute

Quick start

We will suppose here that you want to test your add-on with the stable version of DDEV.

You can add the following step in your workflow:

- uses: ddev/github-action-add-on-test@v2
  with:
    ddev_version: "stable"
    token: ${{ secrets.GITHUB_TOKEN }}
    addon_repository: ${{ env.GITHUB_REPOSITORY }}
    addon_ref: ${{ env.GITHUB_REF }}

This step will install the latest stable version of DDEV and run bats tests command from the source folder of your add-on.

(The source folder of your add-on must contain a tests folder with at least a bats file, as it is the case if you have used the DDEV addon template to create your add-on.)

Inputs

Available keys

The following keys are available as step.with keys:

---

• ddev_version (String)

DDEV version that will be installed before your tests.

Not required.

Default: stable.

Allowed values are: stable, HEAD.

---

• token (String)

A GitHub Personal Access Token used by the debug and run test steps.

Required.

Example: ${{ secrets.GITHUB_TOKEN }}.

---

• addon_repository(String)

GitHub repository of the tested addon ({owner}/{repo}). Will be used as the repository key during a checkout action

Required.

Example: ${{ env.GITHUB_REPOSITORY }}.

---

• addon_ref(String)

GitHub reference of the tested addon. Will be used as the ref key during a checkout action

Required.

Example: ${{ env.GITHUB_REF }}.

---

• addon_path(String)

Path (relative to $GITHUB_WORKSPACE ) where the addon will be cloned by a checkout action. Will be used as the path key of the checkout action

Not required.

Default: ./

---

• debug_enabled (Boolean)

If true, a tmate session will be accessible before the tests step. See action-tmate for more details.

Not required.

Default: false.

---

• disable_checkout_action (Boolean)

If you need to check out your add-on source code with some specific inputs (submodules, ssh-key, etc.), or you need to perform some extra steps between checkout and DDEV installation steps, you can disable the default checkout action by setting true for this input.

Not required.

Default: false.

---

• test_command (String)

If you want to run a customized test command, you can use this input.

If it's empty, the test command will be bats tests --filter-tags !release during push or pull request workflows and bats tests otherwise.

Not required.

Default: "".

For more details, see below.

---

Usage

Test your DDEV add-on

If your add-on is based on the DDEV add-on template repository, you should have a tests folder containing a test.bats file.

Using this GitHub action, a .github/workflows/tests.yml file could have the following content:

name: tests
on:
  pull_request:
  push:
    branches: [main]
    paths-ignore:
      - "**.md"

  schedule:
    - cron: "25 08 * * *"

  workflow_dispatch:
    inputs:
      debug_enabled:
        type: boolean
        description: Debug with tmate
        default: false

permissions:
  contents: read

jobs:
  tests:
    strategy:
      matrix:
        ddev_version: [stable, HEAD]
      fail-fast: false

    runs-on: ubuntu-latest

    steps:
      - uses: ddev/github-action-add-on-test@v2
        with:
          ddev_version: ${{ matrix.ddev_version }}
          token: ${{ secrets.GITHUB_TOKEN }}
          debug_enabled: ${{ github.event.inputs.debug_enabled }}
          addon_repository: ${{ env.GITHUB_REPOSITORY }}
          addon_ref: ${{ env.GITHUB_REF }}

bats tags and the test_command input

By default, this GitHub action is configured to exclude release tagged tests during push and pull_request workflows by using the bats tests --filter-tags '!release' command.

For other workflows, the default command is bats tests, meaning all tests, regardless of their tags, will run.

To tag a test with a release tag, add # bats test_tags=release above the @test line in your bats file:

# bats test_tags=release
@test "install from release" {
  ...
  <run your test here>
  ...
}

This setup keeps release-specific tests out of everyday workflows unless you set a custom test_command.

For more information on bats tags and filtering tests by tags, refer to the bats documentation.

Preserving Artifacts

GitHub Actions provides a UI for browsing test artifacts. To use it, store $TESTDIR in $GITHUB_ENV within your Bats tests (see example), and configure your job as follows:

jobs:
  tests:
    steps:
      ...

      # Optionally, you may need to zip some artifacts before uploading them
      # to fix this error: "The path for one of the files in artifact is not valid"
      # - name: Zip artifacts that can't be processed by actions/upload-artifact
      #   if: always()
      #   run: |
      #     for d in ${{ env.TESTDIR }}*/; do
      #       if [ -d "$d/path/to/directory" ]; then
      #         (cd "$d/path/to" && zip -r directory.zip directory)
      #       fi
      #     done

      - name: Upload artifacts
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: artifact-${{ matrix.ddev_version }}
          path: |
            ${{ env.TESTDIR }}*/tests
            ${{ env.TESTDIR }}*/web/*.junit.xml
            ${{ env.TESTDIR }}*/path/to/directory.zip

License

Apache

Contribute

Anyone is welcome to submit a pull request to this repository.

For more details on development processes, please read the developer guide.

Contributed and maintained by julienloizelet