actions/run-tests/README.md

# Run Tests

Language-agnostic composite action that executes a project's test suite with optional setup and failure-artifact upload. Designed for Forgejo Actions (works on GitHub Actions too).

## Inputs

| Input | Required | Default | Description |
|---|---|---|---|
| `command` | yes | — | Test command to execute (multiline allowed) |
| `setup` | no | `""` | Setup commands run before tests (install deps, build, etc.) |
| `working-directory` | no | `.` | Directory to run setup and command in |
| `shell` | no | `bash` | Shell for setup and command |
| `artifacts-path` | no | `""` | Glob of paths to upload on failure. Empty disables upload. |
| `artifacts-name` | no | `test-artifacts` | Name of the uploaded artifact bundle |

## Behavior

1. Runs `setup` if provided. Non-zero exit fails the job immediately.
2. Runs `command`. Exit code is captured but not yet propagated.
3. If `command` failed and `artifacts-path` is set, uploads matching files.
4. Re-exits with failure if `command` failed.

This ordering ensures artifacts are always uploaded on failure, even though the job ultimately fails.

## Usage

Each example below is a complete workflow — drop it into `.forgejo/workflows/test.yml` (or `.github/workflows/test.yml`) and adjust `runs-on` to match a label one of your runners is registered with. See [Choosing a runner](#choosing-a-runner) below.

### Node.js

```yaml
name: PR Tests
on: [pull_request]
jobs:
  test:
    runs-on: docker-amd64
    steps:
      - uses: https://code.forgejo.org/actions/checkout@v4
      - uses: https://bitfreedom.net/code/apunkt/actions/run-tests@v1
        with:
          setup: npm ci
          command: npm test
          artifacts-path: |
            coverage/**
            junit.xml
```

### Python (pytest)

```yaml
name: PR Tests
on: [pull_request]
jobs:
  test:
    runs-on: docker-amd64
    steps:
      - uses: https://code.forgejo.org/actions/checkout@v4
      - uses: https://bitfreedom.net/code/apunkt/actions/run-tests@v1
        with:
          setup: |
            python -m pip install --upgrade pip
            pip install -e .[test]
          command: pytest --junitxml=report.xml
          artifacts-path: report.xml
```

### Rust

```yaml
name: PR Tests
on: [pull_request]
jobs:
  test:
    runs-on: docker-amd64
    steps:
      - uses: https://code.forgejo.org/actions/checkout@v4
      - uses: https://bitfreedom.net/code/apunkt/actions/run-tests@v1
        with:
          command: cargo test --all
```

### Java (Gradle)

```yaml
name: PR Tests
on: [pull_request]
jobs:
  test:
    runs-on: docker-amd64
    steps:
      - uses: https://code.forgejo.org/actions/checkout@v4
      - uses: https://bitfreedom.net/code/apunkt/actions/run-tests@v1
        with:
          setup: ./gradlew --version
          command: ./gradlew test
          artifacts-path: |
            **/build/reports/tests/**
            **/build/test-results/**/*.xml
```

### Java (Maven)

```yaml
name: PR Tests
on: [pull_request]
jobs:
  test:
    runs-on: docker-amd64
    steps:
      - uses: https://code.forgejo.org/actions/checkout@v4
      - uses: https://bitfreedom.net/code/apunkt/actions/run-tests@v1
        with:
          setup: mvn --version
          command: mvn -B test
          artifacts-path: |
            **/target/surefire-reports/**
            **/target/failsafe-reports/**
```

### Multi-line command

Any of the examples above can run multiple commands in a single step by passing a YAML block scalar to `command`:

```yaml
      - uses: https://bitfreedom.net/code/apunkt/actions/run-tests@v1
        with:
          command: |
            make lint
            make test
            make integration-test
```

## Choosing a runner

`runs-on` must match the labels a runner was registered with — there is no fuzzy match. If your runners are registered as `docker-amd64` and `docker-arm64`, then `runs-on: docker` will queue forever waiting for a runner that doesn't exist.

### Single architecture

Pick the label that matches your runner:

```yaml
jobs:
  test:
    runs-on: docker-amd64
```

### Both architectures (matrix)

Run the same job on every arch in parallel. Useful when you ship binaries, link against native libraries, or want to catch arch-specific bugs early:

```yaml
jobs:
  test:
    strategy:
      fail-fast: false
      matrix:
        arch: [docker-amd64, docker-arm64]
    runs-on: ${{ matrix.arch }}
    steps:
      - uses: https://code.forgejo.org/actions/checkout@v4
      - uses: https://bitfreedom.net/code/apunkt/actions/run-tests@v1
        with:
          command: ./run-tests.sh
```

`fail-fast: false` lets the other arch finish even if one fails, so you see both results.

### Does the architecture matter for the tests?

- **Pure JVM, Python, or Node** with no native dependencies: only execution speed differs.
- **Native code** (Rust, C/C++, JNI, Python wheels like `numpy`/`cryptography`, Node modules built with `node-gyp`): the compiled artifact is arch-specific. Same source, different binary — running the matrix exercises both.
- **Container images pulled during setup**: must publish a manifest for the runner's arch. Most official images do; some niche ones are amd64-only and will fail on arm64.

## Making it a merge gate

This action alone does not block merges. To enforce passing tests before merge on Forgejo:

1. Repo → **Settings → Branches → Protected Branches**
2. Add a rule for `main` (or your default branch)
3. Enable **Require status checks to pass before merging**
4. Add the workflow job name (e.g. `test`) to the required checks list

After the workflow has run at least once on a PR, the check name will appear in the dropdown.

## Notes

- `runs-on` must match a label your runner was registered with — see [Choosing a runner](#choosing-a-runner). The GitHub-style `ubuntu-latest` typically does not exist on Forgejo.
- Action references must use full URLs on Forgejo (`https://code.forgejo.org/actions/checkout@v4`), unlike GitHub where `actions/checkout@v4` is shorthand.
- The failure-artifact upload uses [`forgejo/upload-artifact`](https://code.forgejo.org/forgejo/upload-artifact), which is API-compatible with `actions/upload-artifact` and works on both Forgejo and GitHub.