solpbc.org
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# Use comprehensive mock journal data for testing
21os.environ["_SOLSTONE_JOURNAL_OVERRIDE"] = "tests/fixtures/journal"
22# Now all journal operations work with test data
23```
24
25The `tests/fixtures/journal/` directory contains a complete mock journal structure with sample facets, agents, transcripts, and indexed data for testing.
26
27## Running Tests
28
29- `make test` for unit tests
30- `make test-apps` to run app tests
31- `make test-integration` for integration tests
32- `make test-all` to run all tests (core + apps + integration)
33- `make test-only TEST=path` to run specific tests
34- `make coverage` to generate a coverage report
35- `make ci` before committing (formats, lints, tests)
36- Always run `sol restart-convey` after editing `convey/` or `apps/` to reload code
37- Use `sol screenshot <route>` to capture UI screenshots for visual testing
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, take screenshots or hit endpoints:
48
49```bash
50export _SOLSTONE_JOURNAL_OVERRIDE=tests/fixtures/journal
51export PATH=$(pwd)/.venv/bin:$PATH
52sol screenshot / -o scratch/home.png
53curl -s http://localhost:$(cat tests/fixtures/journal/health/convey.port)/
54```
55
56Notes:
57
58- Agents won't execute without API keys — this is expected in worktrees
59- Output artifacts go in `scratch/` (git-ignored)
60- Service logs: `tests/fixtures/journal/health/<service>.log`
61- `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