Merge pull request #831 from sockbot/docs/tools-pddbci-testing-instructions

docs: add pddbci testing instructions to tools README
This commit is contained in:
bunnie 2026-05-30 01:27:15 +08:00 committed by GitHub
commit 42b2fcf313
No known key found for this signature in database
GPG key ID: B5690EEEBB952194

View file

@ -80,7 +80,61 @@ For more about `i18n_helper.py` please see the locales [README](../locales/READM
## Testing
_TBD_
The director is overloaded with some Python scripts used for PDDB tests. These probably should be moved to a more appropriate location in the future. However, it is what it is for now.
### Running `pddbci.py` (PDDB Regression/Fuzzing Tests)
`pddbci.py` drives the PDDB regression & fuzzing suite. It calls `cargo xtask pddb-ci`
to generate test images and then runs `pddbdbg.py` to verify them. The
analysis step requires Python 3 and several third-party packages.
#### 1. Create a Python virtual environment
```sh
# From the repository root
python3 -m venv venv
source venv/bin/activate
```
#### 2. Install system build tools
`pyaesni` is a native extension compiled from source. Make sure `cmake`
and `yasm` are installed on your system before proceeding.
#### 3. Install Python dependencies
`pyaesni` must be installed from its Git repository (the PyPI tarball is
missing build files):
```sh
pip install pycryptodome cryptography six
```
Note: `pyaesni` was deprecated because the package does not install on all operating systems. The AES routine has been reverted to the standard Python AES routine which causes the test loop to run a bit slower.
#### 4. Run the regression tests
Choose the `--name` of a database image from `tools/pddb-images`
The database images are generated by code that runs here:
https://github.com/betrusted-io/xous-core/blob/c105531e48c59159c4051fdd9c5e539a5c36377e/services/pddb/src/tests.rs#L592-L596
The images are incremental snapshots of various tests working through the PDDB. In practice, the final test (`basis2`) is the test one would run the fuzzing/regression suite on, and in case of a regression, then one would analyze earlier snapshots to work out the root cause of the regression.
```sh
# From the repository root, with the venv active
python3 tools/pddbci.py --name basis2
```
The `--runs` flag controls iteration count (default 501). Use a smaller
value for a quick smoke test:
```sh
python3 tools/pddbci.py --name basis2 --runs 5
```
You can adjust verbosity with `--loglevel DEBUG`.
## Contribution Guidelines