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

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.)

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: ./

• keepalive (Boolean)

Keeps GitHub from turning off tests after 60 days.

If enabled, action will use keepalive-workflow action when ddev_version has been set to stable.

N.B. If enabled, you have to update the permission of the main workflow to write:

permissions:
  actions: write

Not required.

Default: true.

• keepalive_time_elapsed (String)

Time elapsed from the previous commit to keep the repository active using GitHub API (in days).

Will be used as the time_elapsed key of the keepalive-workflow action.

Not required.

Default: "0".

• 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.

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:
  actions: write

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 }}

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.

Apache

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