# 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

```powershell
.\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:

```powershell
.\scripts\test-integration.ps1 -KeepRunning
```

Or deploy without running tests:

```powershell
.\scripts\deploy-test.ps1
```

## Run One Test from PowerShell

```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:

   ```powershell
   .\scripts\deploy-test.ps1
   ```

3. Open Test Explorer.
4. Run any test in `Cortex.IntegrationTests`.

The tests use:

```text
CORTEX_TEST_BASE_URL
```

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

```text
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