# @testream/upload-action

CLI tool to upload test results to Testream.

## Features

- ✅ Uploads test reports to Testream
- 📎 Automatically uploads test artifacts (screenshots, videos, logs)
- 🔄 Idempotent - safe to re-run on existing reports
- 🔐 Secure API key authentication
- 📊 Detailed upload summary with test statistics
- 🖥️ **CLI Support** - Use via npx or install globally for local/CI usage

## Installation

### As a CLI Tool

```bash
# Use with npx (no installation required)
npx @testream/upload-action --help

# Or install globally
npm install -g @testream/upload-action
```

### As a GitHub Action

No installation needed - reference it directly in your workflow.

## Usage

### CLI Usage

#### Basic Example

```bash
npx @testream/upload-action \
  --report-path ./ctrf-report.json \
  --project-key PROJ \
  --api-key $TESTREAM_API_KEY
```

#### With Git Context

```bash
npx @testream/upload-action \
  --report-path ./ctrf-report.json \
  --project-key PROJ \
  --api-key $TESTREAM_API_KEY \
  --branch main \
  --commit-sha $GITHUB_SHA
```

#### CLI Options

```
Required Options:
  -r, --report-path <path>    Path to CTRF report JSON file
  -p, --project-key <key>     Jira project key (e.g., PROJ)
  -k, --api-key <key>         API key for authentication

Optional Options:
  -c, --commit-sha <sha>      Git commit SHA
  -b, --branch <name>         Git branch name
  -u, --repository-url <url>  Git repository URL
      --build-name <name>     Build name/identifier
      --build-number <num>    Build number
      --build-url <url>       Build URL (CI pipeline URL)
      --test-environment <e>  Test environment (e.g., staging, production, ci)
      --app-name <name>       Application name under test
      --app-version <ver>     Application version under test
      --test-type <type>      Test type (e.g., unit, integration, e2e)
      --test-tool <name>      Override tool name in CTRF report
      --no-upload             Skip uploading (validate + summarize only)
      --fail-on-error         Exit with non-zero code if upload fails
  -h, --help                  Show help message
```

#### Using in CI/CD (Non-GitHub)

**GitLab CI:**
```yaml
test:
  script:
    - npm test
    - npx @testream/upload-action \
        --report-path ctrf-report.json \
        --project-key $PROJECT_KEY \
        --api-key $TESTREAM_API_KEY \
        --branch $CI_COMMIT_BRANCH \
        --commit-sha $CI_COMMIT_SHA
```

**CircleCI:**
```yaml
- run:
    name: Upload test results
    command: |
      npx @testream/upload-action \
        --report-path ctrf-report.json \
        --project-key $PROJECT_KEY \
        --api-key $TESTREAM_API_KEY \
        --branch $CIRCLE_BRANCH \
        --commit-sha $CIRCLE_SHA1
```

**Jenkins:**
```groovy
sh '''
  npx @testream/upload-action \
    --report-path ctrf-report.json \
    --project-key ${PROJECT_KEY} \
    --api-key ${TESTREAM_API_KEY} \
    --branch ${GIT_BRANCH} \
    --commit-sha ${GIT_COMMIT}
'''
```

### GitHub Actions Example

```yaml
name: E2E Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - run: npm ci
      - run: npx playwright install --with-deps

      - run: npx playwright test
        continue-on-error: true

      - name: Upload results
        if: always()
        run: |
          npx @testream/upload-action \
            --report-path ctrf-report.json \
            --project-key ECOM \
            --api-key ${{ secrets.TESTREAM_API_KEY }} \
            --branch ${{ github.ref_name }} \
            --commit-sha ${{ github.sha }} \
            --repository-url ${{ github.server_url }}/${{ github.repository }} \
            --build-name ${{ github.workflow }} \
            --build-number ${{ github.run_number }} \
            --build-url ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} \
            --test-environment ci \
            --app-name MyApp \
            --app-version 1.0.0 \
            --test-type e2e \
            --fail-on-error
```



## Test Report Format

The upload tool accepts test reports in a standard JSON format with test results, summary, and artifact references. Test frameworks like Playwright, Jest, Cypress, and others can generate compatible reports.

## Artifact Upload

The action automatically detects and uploads test artifacts (screenshots, videos, logs) referenced in the CTRF report's `attachments` field.

**Requirements:**
- Artifact files must exist at the paths specified in CTRF
- Paths can be relative or absolute
- Missing files will log warnings but won't fail the action

**Supported artifact types:**
- 📸 Screenshots (`image/*` MIME types)
- 🎥 Videos (`video/*` MIME types)
- 📄 Logs (other MIME types)



## Error Handling

The action handles various error scenarios gracefully:

| Scenario | Behavior |
|----------|----------|
| Report file not found | ❌ Action fails |
| Invalid JSON in report | ❌ Action fails |
| Invalid CTRF structure | ❌ Action fails |
| API connection failure | ❌ Action fails |
| Report already exists (409) | ⚠️ Warning, action succeeds |
| Artifact file missing | ⚠️ Warning, continues |
| Artifact upload fails | ⚠️ Warning, continues |

## Security

- Store API keys in GitHub Secrets
- Never commit API keys to repository
- Use `secrets.` context in workflows
- API keys transmitted via secure headers

```yaml
# ✅ Correct
api-key: ${{ secrets.TESTREAM_API_KEY }}

# ❌ Wrong
api-key: 'my-api-key-123'
```

## Troubleshooting

### "Failed to read report file"

Ensure the `report-path` points to the correct CTRF report location. Check your test framework's output directory.

### "Invalid CTRF report structure"

Verify your report includes required fields:
- `reportId`
- `results.tests` (array)
- `results.summary` (object)

### "API ingest failed: HTTP 401"

Check that your API key is correct and stored in GitHub Secrets.

### "Artifact file not found"

Artifact paths in CTRF must match actual file locations. Verify files exist before running the action.

## Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run `npm run all` to format, lint, and build
5. Submit a pull request

## Related

- [@testream/playwright-reporter](https://www.npmjs.com/package/@testream/playwright-reporter) - Playwright reporter with automatic upload

## License

Proprietary - See LICENSE file

