cortex/docs/testing.md

Testing Guide

Cortex has two test modes:

• normal tests through scripts\test.ps1
• local end-to-end integration tests through scripts\test-integration.ps1

The integration tests are ordinary xUnit tests and can be run individually from Visual Studio Test Explorer.

Test Stack

The test stack is isolated from the dev stack.

Service	Test value
Compose project	cortex-test
App	http://localhost:5217
MCP endpoint	http://localhost:5217/mcp
PostgreSQL	localhost:55439
Embeddings	http://localhost:8188

Full Integration Pipeline

.\scripts\test-integration.ps1

This performs:

1. Reset test database.
2. Start test db and embeddings.
3. Build test app image.
4. Apply migrations.
5. Start test app.
6. Wait for health.
7. Run xUnit integration tests.
8. Stop test stack unless -KeepRunning is supplied.

Keep Test Stack Running

Use this before running individual tests from Visual Studio Test Explorer:

.\scripts\test-integration.ps1 -KeepRunning

Or deploy without running tests:

.\scripts\deploy-test.ps1

Run One Test from PowerShell

.\scripts\test-integration.ps1 -Filter "FullyQualifiedName~SearchTests"

Run Tests from Visual Studio

1. Open Cortex.slnx in Visual Studio.

2. Start the test stack:

   .\scripts\deploy-test.ps1
   

3. Open Test Explorer.

4. Run any test in Cortex.IntegrationTests.

The tests use:

CORTEX_TEST_BASE_URL

If that environment variable is not set, they default to:

http://localhost:5217

Test Isolation

Each integration test creates a unique project name. The scripted pipeline resets the test database before a normal run. Individual Visual Studio runs can leave data behind safely because each test uses its own project.

Current Coverage

The integration suite covers:

• health endpoint
• MCP tool discovery
• project creation
• duplicate project behavior
• missing project failure for add
• add/update/delete item
• soft delete hiding items from search
• project-scoped search isolation
• global search
• category filtering