> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clickproof.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Action reference

> All inputs and outputs for clickproof-ai/run-tests.

`clickproof-ai/run-tests` is a composite Action. It needs `bash`, `curl`, and
`jq`, all preinstalled on GitHub-hosted runners.

```yaml theme={null}
- uses: clickproof-ai/run-tests@v1
  with:
    api-key: ${{ secrets.CLICKPROOF_API_KEY }}
    project: your-project-id
    build: path/to/app.apk
```

## Inputs

<ParamField path="api-key" type="string" required>
  clickproof API key (`cp_live_…`). Store it as a repository secret and pass
  `${{ secrets.CLICKPROOF_API_KEY }}` — never hard-code it.
</ParamField>

<ParamField path="project" type="string" required>
  The project id to test.
</ParamField>

<ParamField path="build" type="string" required>
  Path to the build to upload: `.apk` for Android, or a zipped simulator `.app`
  for iOS. A device `.ipa` cannot run on a simulator and is refused.
</ParamField>

<ParamField path="test-id" type="string">
  Run a single test by id. Omit to run every test in the project (a suite).
</ParamField>

<ParamField path="base-url" type="string" default="https://clickproof.app">
  clickproof base URL. Override to target staging or a custom domain.
</ParamField>

<ParamField path="poll-timeout" type="number" default="1200">
  Maximum seconds to wait for all runs to finish before failing.
</ParamField>

<ParamField path="poll-interval" type="number" default="10">
  Seconds between status polls.
</ParamField>

<ParamField path="fail-on-failure" type="boolean" default="true">
  Fail the job when any test fails or errors. Set `false` for report-only runs
  that never fail the build.
</ParamField>

## Outputs

<ResponseField name="passed" type="number">
  Number of tests that passed.
</ResponseField>

<ResponseField name="failed" type="number">
  Number of tests that failed or errored.
</ResponseField>

<ResponseField name="total" type="number">
  Total number of tests run.
</ResponseField>

## Using outputs

```yaml theme={null}
- uses: clickproof-ai/run-tests@v1
  id: clickproof
  with:
    api-key: ${{ secrets.CLICKPROOF_API_KEY }}
    project: your-project-id
    build: app.apk

- run: echo "Passed ${{ steps.clickproof.outputs.passed }} / ${{ steps.clickproof.outputs.total }}"
```

## What it does

<Steps>
  <Step title="Upload">
    `POST /api/v1/projects/:id/build` — uploads your build.
  </Step>

  <Step title="Trigger">
    `POST /api/v1/projects/:id/runs` — starts the test(s).
  </Step>

  <Step title="Poll">
    `GET /api/v1/runs/:id` — polls each run until it reaches a terminal status.
  </Step>

  <Step title="Report">
    Writes the results table to the job summary and exits non-zero on any
    failure.
  </Step>
</Steps>