Module testing 

Testing utilities for FORGE applications.

This module provides comprehensive testing infrastructure for all FORGE function types:

• Queries (read-only database access)
• Mutations (write operations + job/workflow dispatch)
• Actions (external HTTP calls)
• Jobs (background processing)
• Crons (scheduled tasks)
• Workflows (durable multi-step processes)

Philosophy

Following sqlx’s testing philosophy, we recommend testing against real databases rather than mocks. However, for unit tests that don’t need database access, the test contexts can be used without a database connection.

Zero-Config Database

TestDatabase::embedded() automatically downloads and starts an embedded PostgreSQL instance - no configuration required. This is the recommended approach for tests.

Example

use forge::prelude::*;

#[tokio::test]
async fn test_authenticated_query() {
    let ctx = TestQueryContext::builder()
        .as_user(Uuid::new_v4())
        .with_role("admin")
        .build();

    assert!(ctx.auth.is_authenticated());
    assert!(ctx.auth.has_role("admin"));
}

Modules

assertions

Test assertion macros and helpers.

context

Test context builders for all FORGE function types.

db

Database provisioning for tests.

mock_dispatch

Mock dispatchers for testing job and workflow dispatch.

mock_http

HTTP mocking utilities for testing.

Structs

DispatchedJob

Record of a dispatched job.

IsolatedTestDb

A test database that exists for the lifetime of a single test.

MockHttp

Mock HTTP client for testing.

MockHttpBuilder

Builder for MockHttp.

MockJobDispatch

Mock job dispatcher for testing.

MockRequest

Mock HTTP request.

MockResponse

Mock HTTP response.

MockWorkflowDispatch

Mock workflow dispatcher for testing.

StartedWorkflow

Record of a started workflow.

TestActionContext

Test context for action functions.

TestActionContextBuilder

Builder for TestActionContext.

TestCronContext

Test context for cron functions.

TestCronContextBuilder

Builder for TestCronContext.

TestDatabase

Database access for tests.

TestJobContext

Test context for job functions.

TestJobContextBuilder

Builder for TestJobContext.

TestMutationContext

Test context for mutation functions.

TestMutationContextBuilder

Builder for TestMutationContext.

TestProgressUpdate

Progress update recorded during testing.

TestQueryContext

Test context for query functions.

TestQueryContextBuilder

Builder for TestQueryContext.

TestWorkflowContext

Test context for workflow functions.

TestWorkflowContextBuilder

Builder for TestWorkflowContext.

Constants

DEFAULT_JOB_TIMEOUT

Default job test timeout.

DEFAULT_TEST_TIMEOUT

Default test timeout.

DEFAULT_WORKFLOW_TIMEOUT

Default workflow test timeout.

Functions

assert_contains

Assert that an array contains an element matching a predicate.

assert_json_matches

Assert that a value matches a JSON pattern (partial matching).

error_contains

Check if an error message contains a substring.

validation_error_for_field

Check if a validation error contains a specific field.