Skip to main content
Version: v2.0

Testing

Run the checks that match the area you changed. Do not open a pull request without testing the part of the product you touched.

What To Record In The PR​

Your pull request should say:

  • what you verified locally
  • what tests you added or updated
  • what still needs QA

Loading Environment Variables​

The API, SDK, and services tests run against a live stack, so start Agenta locally first (see Development Mode). The test commands need the same environment variables the stack was started with, in particular AGENTA_API_URL and AGENTA_AUTH_KEY.

Add this helper to your ~/.bashrc or ~/.zshrc:

load-env() {
    local env_file="${1:-.env}"
    if [[ ! -f "$env_file" ]]; then
        echo "Error: File '$env_file' not found."
        return 1
    fi
    set -o allexport && source "$env_file" && set +o allexport
}

Then source the env file you deployed with before running tests:

load-env hosting/docker-compose/oss/.env.oss.dev

If you use a different shell, the equivalent one-liner is:

export $(grep -v '^#' hosting/docker-compose/oss/.env.oss.dev | xargs)

Each Python test runner also accepts --env-file <path> directly if you prefer not to export the variables.

API Tests​

Install dependencies first (from api/):

uv sync --locked

This also installs the local Python SDK from sdks/python in editable mode. You do not need to install it separately.

Then run the suite through the test runner:

uv run --no-sync python run-tests.py

Or point the runner at a smaller target:

uv run --no-sync python run-tests.py oss/tests/pytest/acceptance/workflows/

The runner wraps pytest. It picks the OSS or EE test tree based on AGENTA_LICENSE and passes any extra flags straight to pytest.

SDK Tests​

Install dependencies first (from sdks/python/):

uv sync --locked

Then run the suite, or only the unit tests:

uv run --no-sync python run-tests.py
uv run --no-sync python run-tests.py oss/tests/pytest/unit/

Services Tests​

Install dependencies first (from services/):

uv sync --locked

Then run the suite:

uv run --no-sync python run-tests.py

Web Tests​

Install dependencies first (from web/):

pnpm install

Then from web/tests/, run the full acceptance suite:

pnpm test:acceptance

Or the smoke suite for a smaller target:

pnpm test:smoke

Web tests may need Testmail credentials. Check web/tests/README.md if you need the full setup.

More Detail​

For the full testing reference, read docs/designs/testing/README.md. That document covers the full test layout, filters, and runner details across the monorepo.