Testing¶

Running the Test Suite¶

# Fast PR suites
make test-pr

# Redis-backed component integration tests
make test-integration

# Deterministic end-to-end smoke tests
make test-e2e

# Specific test file
uv run pytest tests/unit/test_workflow.py -v

# With coverage
make coverage

Integration tests use FORGE_TEST_REDIS_URL when set and otherwise start a pinned Redis Stack testcontainer. CI sets FORGE_REQUIRE_TEST_REDIS=1, so a missing infrastructure dependency fails the gate instead of silently skipping it.

Webhook Event Timestamps¶

WebhookEvent generates timezone-aware UTC creation and completion timestamps. The Jira webhook route carries the creation timestamp into the queued message. The event-model regression tests cover creation plus completed, failed, and duplicate transitions, checking that timestamps are current and comparable. Those tests treat deprecation warnings as errors even though the default suite filters them. To run the entire event-model file with that stricter policy:

uv run pytest tests/unit/models/test_events.py -W error::DeprecationWarning -q

Linting and Type Checking¶

Before submitting a PR, these must all pass:

make lint
uv run mypy src/forge/       # type check

Payload-Based Testing¶

Test workflow stages without live webhooks using sample payloads from tests/payloads/.

# Trigger a Jira issue-created event
curl -X POST http://localhost:8000/api/v1/webhooks/jira \
  -H "Content-Type: application/json" \
  -d @tests/payloads/jira-feature-created.json

# Trigger a GitHub PR review
curl -X POST http://localhost:8000/api/v1/webhooks/github \
  -H "Content-Type: application/json" \
  -d @tests/payloads/github-pr-approved.json

See the Developer Guide for the full set of payloads and how to trigger specific workflow stages.

Testing CI Skip Commands¶

Post a PR comment via the GitHub API:

curl -X POST \
  "https://api.github.com/repos/your-org/your-repo/issues/123/comments" \
  -H "Authorization: token $GITHUB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"body": "/forge skip-gate e2e-openstack"}'

Then trigger a check run webhook to see Forge re-evaluate CI with the skip applied.

Debugging¶

Snapshot and Restore Checkpoints¶

# Capture current workflow state
uv run forge snapshot --ticket PROJ-123

# Restore to a previous snapshot
uv run forge restore --ticket PROJ-123 --snapshot snapshots/PROJ-123-2024-01-01.json

Inspect Redis State¶

redis-cli -p 6380

# List all workflow checkpoints
KEYS forge:checkpoint:*

# View a specific checkpoint
GET forge:checkpoint:PROJ-123

Worker Logs¶

The worker logs each node execution with the ticket key and node name. Use these to trace where a workflow stopped:

uv run forge worker 2>&1 | grep "PROJ-123"

See the Developer Guide for patching checkpoints directly and other advanced debugging tools.

End-to-End Smoke Testing¶

Forge provides an automated end-to-end smoke test CLI command to verify that state checkpointing, the container runtime sandbox, model provider API connectivity, and the Deep Agent system are fully functional.

uv run forge smoke-test

This command runs completely offline from Jira/production branches, performing all actions in a disposable workspace: 1. Diagnostic Graph Execution: Compiles a 2-node LangGraph and executes it with the configured Redis state checkpointer, verifying workflow resumption. 2. Workspace Setup & Container Verification: Launches a rootless Podman environment inside a temporary folder with a mocked Git tree. 3. Container Agent Execution & Verification: Spawns the real agent inside the container, instructs it to create a specific verification file, and asserts that the file is successfully populated.