personal memory agent
1# Testing
2
3## Test Structure
4
5- **Framework**: pytest with coverage reporting
6- **Unit Tests**: `tests/` root directory
7 - Fast, no external API calls
8 - Use `tests/fixtures/journal/` mock data
9 - Test individual functions and modules
10- **Integration Tests**: `tests/integration/` subdirectory
11 - Test real backends (Anthropic, OpenAI, Google)
12 - Require API keys in `.env`
13 - Test end-to-end workflows
14- **Naming**: Files `test_*.py`, functions `test_*`
15- **Fixtures**: Shared fixtures in `tests/conftest.py`
16
17## Fixture Journal
18
19```python
20# The autouse set_test_journal_path fixture in tests/conftest.py does this
21# for unit tests. Set it explicitly only when a test needs a different journal.
22os.environ["SOLSTONE_JOURNAL"] = "tests/fixtures/journal"
23# Now all journal operations work with test data
24```
25
26The `tests/fixtures/journal/` directory contains a complete mock journal structure with sample facets, agents, transcripts, and indexed data for testing.
27
28## Running Tests
29
30- `make test` for unit tests
31- `make test-apps` to run app tests
32- `make test-integration` for integration tests
33- `make test-all` to run all tests (core + apps + integration)
34- `make test-only TEST=path` to run specific tests
35- `make coverage` to generate a coverage report
36- `make ci` before committing (formats, lints, tests)
37- Always run `sol restart-convey` after editing `solstone/convey/` or `solstone/apps/` to reload code
38
39## Worktree Development
40
41Run the full stack (supervisor + callosum + sense + cortex + convey) against test fixture data:
42
43```bash
44make dev # Start stack (Ctrl+C to stop)
45```
46
47In a second terminal, hit endpoints:
48
49```bash
50export SOLSTONE_JOURNAL=tests/fixtures/journal
51export PATH=$(pwd)/.venv/bin:$PATH
52curl -s http://localhost:$(cat tests/fixtures/journal/health/convey.port)/
53```
54
55Notes:
56
57- Agents won't execute without API keys — this is expected in worktrees
58- Output artifacts go in `scratch/` (git-ignored)
59- Service logs: `tests/fixtures/journal/health/<service>.log`
60- `make dev` writes runtime artifacts (stats cache, health logs, task logs) into the fixtures journal — these are covered by `tests/fixtures/journal/.gitignore` and should never be committed