# Development Scripts

## test-ci-locally.sh

Tests the Gitea Actions workflow locally using `act_runner` 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 Gitea's official `act_runner` to execute the workflow in a containerized environment.

### Usage

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

### What it does

1. Loads environment variables from `.env` file
2. Runs `gitea/act_runner:latest` Docker container with:
   - Docker socket mounted (so act_runner can create containers)
   - Current directory mounted as workspace
   - Secrets passed from `.env` file
3. Executes `.gitea/workflows/magnitude.yml` using act_runner's `exec` command
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 Gitea's act_runner to execute the workflow YAML file. Act_runner creates containers according to the workflow definition, which in turn uses `docker-compose.ci.yml` to set up the test environment:

```
act_runner (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)
```

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