# Testing

`boru/ai` supports three practical test layers:

- fast unit tests
- integration tests with fake HTTP and real public library seams
- DB-backed integration tests gated by explicit test DB env vars

## Local env files

The test bootstrap loads these files automatically when present:

- `.env.test.local`
- `.env.test`
- `.env.local`
- `.env`

Later files only fill missing values by default. Existing process env vars still win.

These files are ignored by git.

Start from `.env.example` and create `.env.test.local` for local test-only settings.

## DB-backed integration tests

DB integration tests are opt-in. They only run when:

- `AI_TEST_DB_ENABLED=1`
- the configured database is reachable
- a simple live query succeeds

Supported env vars:

- `AI_TEST_DB_ENABLED`
- `AI_TEST_DB_HOST`
- `AI_TEST_DB_PORT`
- `AI_TEST_DB_NAME`
- `AI_TEST_DB_USER`
- `AI_TEST_DB_PASS`
- `AI_TEST_DB_TYPE`

Example:

```dotenv
AI_TEST_DB_ENABLED=1
AI_TEST_DB_HOST=127.0.0.1
AI_TEST_DB_PORT=3306
AI_TEST_DB_NAME=ai_test
AI_TEST_DB_USER=ai_test
AI_TEST_DB_PASS=secret
AI_TEST_DB_TYPE=mysql
```

Then run:

```bash
./vendor/bin/phpunit -c phpunit.integration.xml
```

The DB integration harness creates unique table names per test run so one shared test database is sufficient.

## PHPUnit configs

Default fast suite:

```bash
./vendor/bin/phpunit -c phpunit.xml
```

This excludes `tests/Integration`.

Integration suite:

```bash
./vendor/bin/phpunit -c phpunit.integration.xml
```

This runs only `tests/Integration`, including the DB-backed integration tests when `AI_TEST_DB_ENABLED=1`.

## Safety

Use a dedicated test-only database and a least-privilege test user.

The DB-backed tests create and drop tables and should never point at production or shared application schemas.
