# Development Scripts

## test-ci-locally.sh

Tests the CI workflow locally by running the **exact same docker-compose command** that the Gitea Actions workflow runs.

### Purpose

When CI tests fail, this script reproduces the exact CI environment locally to debug issues without repeatedly pushing to trigger CI runs. It runs `docker-compose.ci.yml` with the same parameters as the CI workflow, so you're testing in an identical environment.

### Usage

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

Or run docker-compose directly (this is what the script does):

```bash
docker compose -f docker-compose.ci.yml --profile test up \
  --abort-on-container-exit \
  --exit-code-from magnitude
```

### What it does

1. Checks that `.env` file exists
2. Runs `docker compose -f docker-compose.ci.yml --profile test up`
3. This starts all services:
   - **surrealdb**: In-memory database with health check
   - **nextjs**: Node.js container running `pnpm dev` with health check
   - **magnitude**: Playwright container running the test suite
4. Waits for tests to complete
5. Exits with magnitude's exit code
6. Shows service logs on failure
7. Cleans up containers and volumes

### Requirements

- Docker and docker-compose installed
- `.env` file with test credentials

### Services Architecture

The script starts a containerized test environment with proper health checks and dependencies:

```
magnitude (Playwright container - runs tests)
  ↓ depends on (waits for health check)
nextjs (Node.js container - runs pnpm dev)
  ↓ depends on (waits for health check)
surrealdb (SurrealDB container - in-memory mode)
```

All services share the same network:
- Next.js accesses SurrealDB via `ws://surrealdb:8000/rpc`
- Magnitude accesses Next.js via `http://localhost:3000`

### Why This Approach?

This is simpler and more accurate than using workflow runner tools like `act` or `act_runner` because:

1. **Identical to CI**: The CI workflow (`.gitea/workflows/magnitude.yml`) literally runs this docker-compose command, so you're testing the exact same thing
2. **No Additional Tools**: Doesn't require `act`, `act_runner`, or any workflow execution tools
3. **Direct Debugging**: Runs the actual test commands directly, making it easier to see what's happening
4. **Faster**: No overhead from workflow interpretation or runner setup

### 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 reproduce **exactly**
3. The script will show the same output as CI
4. Debug with docker-compose logs if needed:
   ```bash
   docker compose -f docker-compose.ci.yml logs surrealdb
   docker compose -f docker-compose.ci.yml logs nextjs
   docker compose -f docker-compose.ci.yml logs magnitude
   ```
5. Fix issues locally
6. Run script again to verify fix
7. Commit and push once tests pass locally

This is **much** faster than debugging via CI push cycles and gives you identical results!