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

### Node.js

```yaml
name: PR Tests
on: [pull_request]
jobs:
  test:
    runs-on: docker
    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
- 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
- uses: https://bitfreedom.net/code/apunkt/actions/run-tests@v1
  with:
    command: cargo test --all
```

### Java (Gradle)

```yaml
- 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
- 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

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

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

- Forgejo runners often use the `docker` label rather than `ubuntu-latest`. Adjust `runs-on` per your runner setup.
- 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.