app/scripts

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

./scripts/test-ci-locally.sh

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

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:

   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!