Skip to content

Commit 8bc83df

Browse files
claudeclaude
committed
Restore tests/README.md - needed for test documentation
The tests directory structure and usage should be documented. Restored tests/README.md which explains: - Test organization (unit/integration/e2e) - How to run tests - Coverage reporting - Test fixtures
1 parent 6ba5e57 commit 8bc83df

File tree

1 file changed

+193
-0
lines changed

1 file changed

+193
-0
lines changed

‎tests/README.md‎

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
# Test Suite for python_prtree
2+
3+
This directory contains a comprehensive test suite for python_prtree, organized by test type and functionality.
4+
5+
## Directory Structure
6+
7+
```
8+
tests/
9+
├── unit/ # Unit tests (individual features)
10+
│ ├── test_construction.py
11+
│ ├── test_query.py
12+
│ ├── test_batch_query.py
13+
│ ├── test_insert.py
14+
│ ├── test_erase.py
15+
│ ├── test_persistence.py
16+
│ ├── test_rebuild.py
17+
│ ├── test_intersections.py
18+
│ ├── test_object_handling.py
19+
│ ├── test_properties.py
20+
│ └── test_precision.py
21+
│
22+
├── integration/ # Integration tests (feature combinations)
23+
│ ├── test_insert_query_workflow.py
24+
│ ├── test_erase_query_workflow.py
25+
│ ├── test_persistence_query_workflow.py
26+
│ ├── test_rebuild_query_workflow.py
27+
│ └── test_mixed_operations.py
28+
│
29+
├── e2e/ # End-to-end tests (user scenarios)
30+
│ ├── test_readme_examples.py
31+
│ ├── test_regression.py
32+
│ └── test_user_workflows.py
33+
│
34+
├── legacy/ # Original test file (kept for reference)
35+
│ └── test_PRTree.py
36+
│
37+
├── conftest.py # Shared fixtures and configuration
38+
└── README.md # This file
39+
40+
## Running Tests
41+
42+
### Run all tests
43+
```bash
44+
pytest tests/
45+
```
46+
47+
### Run specific test category
48+
```bash
49+
# Unit tests only
50+
pytest tests/unit/
51+
52+
# Integration tests only
53+
pytest tests/integration/
54+
55+
# E2E tests only
56+
pytest tests/e2e/
57+
```
58+
59+
### Run specific test file
60+
```bash
61+
pytest tests/unit/test_construction.py
62+
```
63+
64+
### Run tests for specific dimension
65+
```bash
66+
# Run all PRTree2D tests
67+
pytest tests/ -k "PRTree2D"
68+
69+
# Run all PRTree3D tests
70+
pytest tests/ -k "PRTree3D"
71+
72+
# Run all PRTree4D tests
73+
pytest tests/ -k "PRTree4D"
74+
```
75+
76+
### Run with coverage
77+
```bash
78+
pytest --cov=python_prtree --cov-report=html tests/
79+
```
80+
81+
### Run with verbose output
82+
```bash
83+
pytest -v tests/
84+
```
85+
86+
### Run specific test by name
87+
```bash
88+
pytest tests/unit/test_construction.py::TestNormalConstruction::test_construction_with_valid_inputs
89+
```
90+
91+
## Test Organization
92+
93+
### Unit Tests (`tests/unit/`)
94+
Test individual functions and methods in isolation:
95+
- **test_construction.py**: Tree initialization and construction
96+
- **test_query.py**: Single query operations
97+
- **test_batch_query.py**: Batch query operations
98+
- **test_insert.py**: Insert operations
99+
- **test_erase.py**: Erase operations
100+
- **test_persistence.py**: Save/load operations
101+
- **test_rebuild.py**: Rebuild operations
102+
- **test_intersections.py**: Query intersections operations
103+
- **test_object_handling.py**: Object storage and retrieval
104+
- **test_properties.py**: Properties (size, len, n)
105+
- **test_precision.py**: Float32/64 precision handling
106+
- **test_segfault_safety.py**: Segmentation fault safety tests
107+
- **test_crash_isolation.py**: Crash isolation tests (subprocess)
108+
- **test_memory_safety.py**: Memory safety and bounds checking
109+
- **test_concurrency.py**: Python threading/multiprocessing/async tests
110+
- **test_parallel_configuration.py**: Parallel execution configuration tests
111+
112+
### Integration Tests (`tests/integration/`)
113+
Test interactions between multiple components:
114+
- **test_insert_query_workflow.py**: Insert → Query workflows
115+
- **test_erase_query_workflow.py**: Erase → Query workflows
116+
- **test_persistence_query_workflow.py**: Save → Load → Query workflows
117+
- **test_rebuild_query_workflow.py**: Rebuild → Query workflows
118+
- **test_mixed_operations.py**: Complex operation sequences
119+
120+
### End-to-End Tests (`tests/e2e/`)
121+
Test complete user workflows and scenarios:
122+
- **test_readme_examples.py**: All examples from README
123+
- **test_regression.py**: Known bug fixes and edge cases
124+
- **test_user_workflows.py**: Common user scenarios
125+
126+
## Test Coverage
127+
128+
The test suite covers:
129+
- ✅ All public APIs (PRTree2D, PRTree3D, PRTree4D)
130+
- ✅ Normal cases (happy path)
131+
- ✅ Error cases (invalid inputs)
132+
- ✅ Boundary values (empty, single, large datasets)
133+
- ✅ Precision cases (float32 vs float64)
134+
- ✅ Edge cases (degenerate boxes, touching boxes, etc.)
135+
- ✅ Consistency (query vs batch_query, save/load, etc.)
136+
- ✅ Known regressions (bugs from issues)
137+
- ✅ Memory safety (segfault prevention, bounds checking)
138+
- ✅ Concurrency (threading, multiprocessing, async)
139+
- ✅ Parallel execution (batch_query parallelization)
140+
141+
## Test Matrix
142+
143+
See [docs/TEST_STRATEGY.md](../docs/TEST_STRATEGY.md) for the complete feature-perspective test matrix.
144+
145+
## Adding New Tests
146+
147+
When adding new tests:
148+
149+
1. **Choose the right category**:
150+
- Unit tests: Testing a single feature in isolation
151+
- Integration tests: Testing multiple features together
152+
- E2E tests: Testing complete user workflows
153+
154+
2. **Follow naming conventions**:
155+
```python
156+
def test_<feature>_<scenario>_<expected>():
157+
"""Test description in Japanese and English."""
158+
pass
159+
```
160+
161+
3. **Use parametrization** for dimension testing:
162+
```python
163+
@pytest.mark.parametrize("PRTree, dim", [(PRTree2D, 2), (PRTree3D, 3), (PRTree4D, 4)])
164+
def test_my_feature(PRTree, dim):
165+
pass
166+
```
167+
168+
4. **Use shared fixtures** from `conftest.py` when appropriate
169+
170+
5. **Update TEST_STRATEGY.md** if adding new test perspectives
171+
172+
## Continuous Integration
173+
174+
These tests are run automatically on:
175+
- Every pull request
176+
- Every push to main branch
177+
- Scheduled daily builds
178+
179+
See `.github/workflows/` for CI configuration.
180+
181+
## Known Issues
182+
183+
- Some tests may take longer on slower systems due to large dataset sizes
184+
- Float precision tests are sensitive to numpy/system math libraries
185+
- File I/O tests require write permissions in tmp_path
186+
187+
## Contributing
188+
189+
When contributing tests:
190+
1. Ensure all tests pass locally before submitting PR
191+
2. Add tests for any new features or bug fixes
192+
3. Update this README if adding new test categories
193+
4. Aim for >90% line coverage and >85% branch coverage

0 commit comments

Comments
 (0)