# Development Scripts

## test-ci-locally.sh

Tests the Gitea Actions workflow locally using `act` (nektos/act) in Docker.

### Purpose

When CI tests fail, this script allows you to run the **exact same workflow** (`.gitea/workflows/magnitude.yml`) locally to debug issues without repeatedly pushing to trigger CI runs. It uses `nektos/act` to execute the workflow in a containerized environment, just like GitHub Actions or Gitea Actions would.

### Usage

```bash
./scripts/test-ci-locally.sh
```

### What it does

1. Loads environment variables from `.env` file
2. Runs `nektos/act:latest` Docker container with:
   - Docker socket mounted (so act can create containers)
   - Current directory mounted as workspace
   - Secrets passed from `.env` file
3. Executes `.gitea/workflows/magnitude.yml` using act
4. The workflow then runs its steps:
   - Checkout code
   - Create .env file with secrets
   - Run tests with docker-compose (starts SurrealDB, Next.js, Magnitude)
   - Show logs on failure
   - Upload test results
   - Cleanup

### Requirements

- Docker installed and running
- `.env` file with test credentials and secrets
- Docker socket accessible at `/var/run/docker.sock`

### How It Works

The script uses `nektos/act` to execute the workflow YAML file. Act is compatible with both GitHub Actions and Gitea Actions workflows. It creates containers according to the workflow definition, which in turn uses `docker-compose.ci.yml` to set up the test environment:

```
act (nektos/act Docker container)
  ↓ executes .gitea/workflows/magnitude.yml
  ↓ which runs docker-compose with:
magnitude (Playwright container)
  ↓ depends on (waits for health check)
nextjs (Node.js container running pnpm dev)
  ↓ depends on (waits for health check)
surrealdb (SurrealDB container)
```

### Note on nektos/act vs gitea/act_runner

- `nektos/act` is designed for local workflow testing and is compatible with both GitHub Actions and Gitea Actions
- `gitea/act_runner` is a runner daemon that needs to connect to a Gitea instance and is not designed for offline local testing
- This script uses `nektos/act` which provides the local testing experience similar to running workflows in CI

### Debugging CI Failures

If Gitea Actions fail:

1. Check the workflow logs for errors in Gitea UI
2. Run `./scripts/test-ci-locally.sh` to execute the workflow locally
3. The script will show the same steps and output as CI
4. Fix issues based on the local test results
5. Run script again to verify fix
6. Commit and push once tests pass locally

This is **much** faster than debugging via CI push cycles and gives you the exact same environment!