mirrors/core-lightning
1
0
Fork 0
mirror of https://github.com/ElementsProject/lightning.git synced 2025-03-15 11:59:16 +01:00
Code Issues Projects Releases Wiki Activity

doc: Add GENERATE_EXAMPLES details

Browse source 
Changelog-None.
This commit is contained in:
ShahanaFarooqui 2024-11-26 11:02:49 -08:00 • committed by Rusty Russell
parent 0a7956b6d4
commit 075f180596
2 changed files with 11 additions and 9 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

19
doc/contribute-to-core-lightning/coding-style-guidelines/writing-json-schemas.md
View file

@ -63,13 +63,14 @@ To add conditional fields:
generate the Markdown syntax as `[*index* [*start*] [*limit*]]`.
## Generating Examples in Schema
The `tests/autogenerate-rpc-examples.py` test script regenerates RPC examples for methods defined
in `doc/schemas/lightning-*.json`. These examples are located at the end of each schema page,
detailing `shell` and `json` request formats along with their corresponding `json` responses.
The script utilizes the pytest suite to automate this task by running a test, `test_generate_examples`,
that sets up test nodes, records RPC requests, and captures responses. Any new RPC command's examples
should also be included in this scripts. This test only executes example generation if `GENERATE_EXAMPLES=True`
is set, preventing accidental overwrites from unrelated tests.
The `tests/autogenerate-rpc-examples.py` test script regenerates RPC examples for methods defined
in `doc/schemas/lightning-*.json`, if the environment variable `GENERATE_EXAMPLES` is set to 1.
These examples are located at the end of each schema page, detailing `shell` and `json` request
formats along with their corresponding `json` responses. The script utilizes the pytest suite to
automate this task by running a test, `test_generate_examples`, that sets up test nodes, records
RPC requests, and captures responses. Any new RPC command's examples should also be included in
this scripts. This test only executes example generation if `GENERATE_EXAMPLES=1` is set,
preventing accidental overwrites from unrelated tests.
### Adding New Examples
1. Define a New Function (if needed):
@ -93,7 +94,7 @@ is set, preventing accidental overwrites from unrelated tests.
where `n` can be any number of repetitions. OR by manually running the test multiple times with:
```bash
rm -rf /tmp/ltests* && make -s && VALGRIND=0 TIMEOUT=40 TEST_DEBUG=1 pytest -vvv -n 6 tests/autogenerate-rpc-examples.py
rm -rf /tmp/ltests* && make -s && VALGRIND=0 TIMEOUT=40 TEST_DEBUG=1 GENERATE_EXAMPLES=1 pytest -vvv tests/autogenerate-rpc-examples.py
```
- Identify changing values, and add them to `REPLACE_RESPONSE_VALUES`:
@ -116,7 +117,7 @@ environment variable with a comma-separated list of method names. Eg. `REGENERAT
only regenerate examples for the `getinfo` and `connect` RPCs.
2. To regenerate specific examples, set the REGENERATE environment variable:
```bash
REGENERATE='getinfo,connect' VALGRIND=0 TIMEOUT=10 TEST_DEBUG=1 pytest -vvv -n 6 tests/autogenerate-rpc-examples.py
REGENERATE='getinfo,connect' VALGRIND=0 TIMEOUT=10 TEST_DEBUG=1 GENERATE_EXAMPLES=1 pytest -vvv tests/autogenerate-rpc-examples.py
```
3. Logs are saved in `tests/autogenerate-examples-status.log`, and JSON data is in `tests/autogenerate-examples.json`.
4. Run `make` after the script completes to ensure schema updates are applied in other places too, such as `...msggen/schema.json`.

1
doc/contribute-to-core-lightning/testing.md
View file

@ -78,6 +78,7 @@ PYTEST_TESTS="tests/" - Target a specific set of blackbox tests
SLOW_MACHINE=[0|1] - Set sensible defaults for running tests
in resource-constrained environments.
VALGRIND=[0|1] - Run the tests with Valgrind.
GENERATE_EXAMPLES=[0|1] - Generate examples for RPC documentation.
```
#### Troubleshooting