authgear-server: Skill for Claude Code

Follow this guide when writing e2e tests.

E2E Environment Setup

CRITICAL: All make commands must be run from e2e/ directory, not project root.

Standard Workflow

When starting fresh or after code changes:

cd e2e                          # ← MUST be in e2e directory
make teardown && make setup     # ← Tears down old containers, rebuilds binaries, applies migrations

This command:

• Stops and removes Docker containers (Redis, PostgreSQL, Deno hook server)
• Rebuilds authgear and authgear-portal binaries with latest code
• Applies all database migrations
• Starts services fresh

Running Tests

After setup completes, run tests from the e2e directory:

cd e2e  # ← Must be in e2e directory

# Run a specific test
go test ./pkg/testrunner/ -count 1 -v -timeout 10m -run "TestAuthflow/<folder>/<filename_without_extension>"

# Run all tests
go test ./pkg/testrunner/ -count 1 -v -timeout 10m

When Setup Fails

If make teardown && make setup fails:

1. Try again - transient Docker issues are common:

   cd e2e && make teardown && make setup
   

2. Check if containers are stuck:

   docker ps  # Run from any directory to list containers
   

3. If still failing - ask the user to manually intervene. Do NOT attempt low-level Docker operations (docker-compose down -v, etc.) as these can affect other projects and data.

Always use the Makefile (make teardown && make setup). Do not skip to ./run.sh or other workarounds.

When to Re-setup

Always run make teardown && make setup from e2e/ directory when:

• You modified server code (rebuilds binaries)
• Database schema/migrations changed
• Tests fail with DB schema errors
• Starting fresh after a long break

Overview

E2e tests are YAML files placed under e2e/tests/<feature>/. The test runner auto-discovers all *.test.yaml files. Each file defines one test case.

Test File Structure

name: Human-readable test name
authgear.yaml:           # Optional: config overrides
  extend: path/to/base.yaml   # Optional base config
  override: |
    fraud_protection:
      enabled: true
before:                  # Optional: setup hooks (run before steps)
  - type: custom_sql
    custom_sql:
      path: fixtures.sql
steps:
  - name: step name      # Optional but recommended
    action: create
    input: |
      {
        "type": "signup",
        "name": "default"
      }
    output:
      result: |
        {
          "action": {
            "type": "identify"
          }
        }