---
name: step-03-integration-tests
description: Run integration tests to verify real DB operations
prev_step: steps/step-02-unit-tests.md
next_step: steps/step-04-api-smoke.md
---

# Step 3: Integration Tests

## BLOCKING - All integration tests must pass

### 1. Run integration tests

```bash
dotnet test {TestProject} --no-build --filter "FullyQualifiedName~Integration" --verbosity normal
```

If the filter doesn't match, try:

```bash
dotnet test {TestProject} --no-build --filter "FullyQualifiedName~ControllerIntegrationTests|FullyQualifiedName~RepositoryTests" --verbosity normal
```

### 2. What these tests verify

Integration tests use `SmartStackTestFactory` (WebApplicationFactory with SQLite) to run the REAL application pipeline:

| What | How |
|------|-----|
| Controller routing | HTTP requests hit actual controller endpoints |
| DI pipeline | Real services and repositories are injected |
| Database operations | SQLite in-memory stores and retrieves data |
| Auth middleware | TestAuthHandler provides fake authenticated user |
| Tenant isolation | Requests with different tenant IDs see different data |
| Data persistence | POST creates data, GET retrieves it from DB |

### 3. Evaluate result

- **All tests passed** -> Proceed to step 4
- **Tests failed** -> Common issues:
  - `Program` not accessible -> Add `public partial class Program { }` to Program.cs
  - DbContext configuration error -> Check that SQLite provider is properly configured
  - Service not registered -> Check DI registration in `Program.cs` or startup
  - Migration issue -> Ensure `EnsureCreatedAsync()` works with SQLite
  - Tenant filter issue -> Check global query filters work with test tenant
  - **Fix and re-run until all pass**

### 4. Store state

```
{integration_test_count} = number of tests that passed
{integration_test_result} = PASS or FAIL
```