Testing And Validation
======================

Purpose
-------

This document defines the canonical validation path for changes in this repo.
It is the primary reference for:

- what to run locally before push
- what GitHub runs on pull requests
- what the deploy workflow runs before and after deployment

Local developer validation
--------------------------

Required local regression command before push::

   cd /home/roger/projects/codex_trial/agent_client/server
   UV_CACHE_DIR=/tmp/uv-cache uv run python scripts/release_verify.py pre-deploy

This is the canonical local validation path for deployment-facing changes.

What it covers
--------------

The current pre-deploy gate runs these test modules:

- ``tests.test_api_routers``
- ``tests.test_admin_cli_devices_and_context``
- ``tests.test_admin_cli_exports_stage_repl``
- ``tests.test_admin_cli_jobs_rounds``
- ``tests.test_admin_cli_customers_artifacts``
- ``tests.test_command_registry``
- ``tests.test_config``
- ``tests.test_export_sync_service``
- ``tests.test_final_report_images_service``
- ``tests.test_media_runtime_service``
- ``tests.test_report_image_runtime_service``
- ``tests.test_staging_sync_service``
- ``tests.test_tree_identification_service``

These tests run with CI-safe local defaults:

- ``TRAQ_DATABASE_URL=sqlite+pysqlite:///:memory:``
- ``TRAQ_ENABLE_DISCOVERY=false``
- ``TRAQ_AUTO_CREATE_SCHEMA=false``
- ``TRAQ_ENABLE_FILE_LOGGING=false``

CI validation
-------------

Pull request workflows:

1. PR verification

   - workflow: ``.github/workflows/server-pr-verification.yml``
   - runs the same canonical pre-deploy gate::

       uv run python scripts/release_verify.py pre-deploy

2. PostgreSQL integration smoke lane

   - workflow: ``.github/workflows/server-postgres-ci.yml``
   - boots temporary PostgreSQL in GitHub Actions
   - runs::

       uv run alembic upgrade head
       uv run python -m unittest tests.test_postgres_ci_smoke

Deployment validation
---------------------

The deploy workflow is:

- ``.github/workflows/server-cloudrun.yml``

It runs:

1. pre-deploy gate
2. image build and push
3. migration job update and execution
4. Cloud Run service deploy
5. post-deploy health verification

Post-deploy verification
------------------------

The canonical post-deploy check is::

   UV_CACHE_DIR=/tmp/uv-cache uv run python scripts/release_verify.py post-deploy

Required environment:

- ``TRAQ_CLOUD_ADMIN_BASE_URL``

Current scope:

- ``GET /health``

Interpretation
--------------

- local regression command:
  developer pre-push check
- PR verification:
  merge gate
- deploy verification:
  release gate
- post-deploy health:
  live-service readiness check

Practical standard
------------------

Before starting a feature branch, assume the required validation path is:

1. targeted tests for the changed area during implementation
2. canonical pre-deploy gate before push or merge
3. PostgreSQL CI lane on pull request
4. deploy workflow on ``main``

If a change is important enough to deploy, it is important enough to survive
the canonical pre-deploy gate.