Skip to content

Commit 9c09a05

Browse files
committed
Better testing docs
1 parent 053163f commit 9c09a05

File tree

2 files changed

+145
-9
lines changed

2 files changed

+145
-9
lines changed

tests/README.md

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
# Xian Network Testing Guide
2+
3+
## Overview
4+
5+
This guide explains how to run and understand the test suite for the Xian Network node. Tests are crucial for ensuring the reliability and correctness of the blockchain implementation.
6+
7+
## Motivation
8+
9+
All tests in Xian run in a standardized environment where variables are controlled and predictable. This ensures:
10+
11+
- Reproducible test outcomes across different environments
12+
- Isolation between test cases
13+
- Clear test failures that can be easily debugged
14+
15+
## Test Architecture
16+
17+
The test suite is organized into several categories:
18+
19+
- **Unit Tests** (`tests/unit/`): Tests for individual components and utility functions
20+
- **System Tests** (`tests/system/`): Tests for core system contracts (currency, vault, members)
21+
- **Integration Tests** (`tests/integration/`): Tests for interactions between components
22+
- **ABCI Method Tests** (`tests/abci_methods/`): Tests for CometBFT ABCI interface
23+
- **Governance Tests** (`tests/governance/`): Tests for on-chain governance mechanisms
24+
25+
## Environment Setup
26+
27+
Tests use these key principles:
28+
29+
1. **Fixture Management**:
30+
- A `.cometbft-fixture` directory contains baseline configurations
31+
- This is copied to `/tmp/cometbft/` at the start of each test
32+
- Tests run against this temporary environment for isolation
33+
- Each test starts with a clean state
34+
35+
2. **Constants Override**:
36+
- `MockConstants` overrides production settings during tests
37+
- This prevents tests from interacting with real blockchain data
38+
39+
## Running the Tests
40+
41+
### Prerequisites
42+
43+
Ensure you have all dependencies installed:
44+
45+
```bash
46+
# Install the package in development mode with test dependencies
47+
pip install -e .
48+
```
49+
50+
### Running Tests with pytest
51+
52+
```bash
53+
# Run all tests
54+
python -m pytest tests/
55+
56+
# Run specific test categories
57+
python -m pytest tests/unit/
58+
python -m pytest tests/system/
59+
python -m pytest tests/integration/
60+
python -m pytest tests/abci_methods/
61+
python -m pytest tests/governance/
62+
63+
# Run a specific test file
64+
python -m pytest tests/system/test_currency.py
65+
66+
# Run a specific test class or method
67+
python -m pytest tests/system/test_currency.py::TestCurrencyContract
68+
python -m pytest tests/system/test_currency.py::TestCurrencyContract::test_transfer
69+
70+
# Run with verbose output
71+
python -m pytest tests/ -v
72+
73+
# Display print statements during tests
74+
python -m pytest tests/ -s
75+
76+
# Run only tests matching a pattern
77+
python -m pytest tests/ -k "transfer"
78+
```
79+
80+
### Running Tests with unittest
81+
82+
```bash
83+
# Run all tests
84+
python -m unittest discover tests
85+
86+
# Run a specific test file
87+
python -m unittest tests/system/test_currency.py
88+
89+
# Run a specific test class
90+
python -m unittest tests.system.test_currency.TestCurrencyContract
91+
92+
# Run a specific test method
93+
python -m unittest tests.system.test_currency.TestCurrencyContract.test_transfer
94+
```
95+
96+
## Writing New Tests
97+
98+
When writing new tests:
99+
100+
1. **Use the fixture system**:
101+
```python
102+
from fixtures.mock_constants import MockConstants
103+
from utils import setup_fixtures, teardown_fixtures
104+
105+
class TestExample(unittest.TestCase):
106+
def setUp(self):
107+
setup_fixtures()
108+
# Additional setup code here
109+
110+
def tearDown(self):
111+
teardown_fixtures()
112+
# Additional cleanup code here
113+
```
114+
115+
2. **Override constants** using `MockConstants`
116+
3. **Ensure proper cleanup** after tests
117+
4. **Make tests independent** from each other
118+
119+
## Test Debugging
120+
121+
If tests are failing:
122+
123+
1. Run with verbose flags (`-v`, `-s`)
124+
2. Check that fixtures are being set up correctly
125+
3. Examine temporary directories created during tests
126+
4. Verify the Python version (tests require Python 3.11.11)
127+
128+
## CI/CD Integration
129+
130+
Tests run automatically on GitHub Actions for:
131+
- Pull requests
132+
- Commits to all branches
133+
- Release processes
134+
135+
The CI pipeline runs tests against a PostgreSQL service for database-dependent tests.
136+
137+
## Best Practices
138+
139+
- Keep tests small and focused on a single feature
140+
- Use descriptive test method names
141+
- Add comments explaining complex test scenarios
142+
- Ensure tests are deterministic (no random behavior)
143+
- Avoid tests with external dependencies when possible
144+
145+
By following this guide, you'll be able to effectively run, debug, and contribute to the Xian Network test suite.

tests/xian-tests.md

Lines changed: 0 additions & 9 deletions
This file was deleted.

0 commit comments

Comments
 (0)