Changeset View
Changeset View
Standalone View
Standalone View
doc/test-shell.md
Test Shell for Interactive Environments | Test Shell for Interactive Environments | ||||
========================================= | ========================================= | ||||
This document describes how to use the `TestShell` submodule in the functional | This document describes how to use the `TestShell` submodule in the functional | ||||
test suite. | test suite. | ||||
The `TestShell` submodule extends the `BitcoinTestFramework` functionality to | The `TestShell` submodule extends the `BitcoinTestFramework` functionality to | ||||
external interactive environments for prototyping and educational purposes. Just | external interactive environments for prototyping and educational purposes. Just | ||||
like `BitcoinTestFramework`, the `TestShell` allows the user to: | like `BitcoinTestFramework`, the `TestShell` allows the user to: | ||||
* Manage regtest bitcoind subprocesses. | * Manage regtest ecashd subprocesses. | ||||
* Access RPC interfaces of the underlying bitcoind instances. | * Access RPC interfaces of the underlying bitcoind instances. | ||||
* Log events to the functional test logging utility. | * Log events to the functional test logging utility. | ||||
The `TestShell` can be useful in interactive environments where it is necessary | The `TestShell` can be useful in interactive environments where it is necessary | ||||
to extend the object lifetime of the underlying `BitcoinTestFramework` between | to extend the object lifetime of the underlying `BitcoinTestFramework` between | ||||
user inputs. Such environments include the Python3 command line interpreter or | user inputs. Such environments include the Python3 command line interpreter or | ||||
[Jupyter](https://jupyter.org/) notebooks running a Python3 kernel. | [Jupyter](https://jupyter.org/) notebooks running a Python3 kernel. | ||||
▲ Show 20 Lines • Show All 130 Lines • ▼ Show 20 Lines | |||||
20XX-XX-XXTXX:XX:XX.XXXXXXX TestFramework (INFO): Not cleaning up dir /path/to/bitcoin_func_test_XXXXXXX on exit | 20XX-XX-XXTXX:XX:XX.XXXXXXX TestFramework (INFO): Not cleaning up dir /path/to/bitcoin_func_test_XXXXXXX on exit | ||||
20XX-XX-XXTXX:XX:XX.XXXXXXX TestFramework (INFO): Tests successful | 20XX-XX-XXTXX:XX:XX.XXXXXXX TestFramework (INFO): Tests successful | ||||
``` | ``` | ||||
The following utility consolidates logs from the bitcoind nodes and the | The following utility consolidates logs from the bitcoind nodes and the | ||||
underlying `BitcoinTestFramework`: | underlying `BitcoinTestFramework`: | ||||
* `/path/to/bitcoin-abc/test/functional/combine_logs.py | * `/path/to/bitcoin-abc/test/functional/combine_logs.py | ||||
'/path/to/bitcoin_func_test_XXXXXXX'` | '/path/to/ecash_func_test_XXXXXXX'` | ||||
## 6. Custom `TestShell` parameters | ## 6. Custom `TestShell` parameters | ||||
The `TestShell` object initializes with the default settings inherited from the | The `TestShell` object initializes with the default settings inherited from the | ||||
`BitcoinTestFramework` class. The user can override these in | `BitcoinTestFramework` class. The user can override these in | ||||
`TestShell.setup(key=value)`. | `TestShell.setup(key=value)`. | ||||
**Note:** `TestShell.reset()` will reset test parameters to default values and | **Note:** `TestShell.reset()` will reset test parameters to default values and | ||||
Show All 9 Lines | |||||
| `loglevel` | `INFO` | Logs events at this level and higher. Can be set to `DEBUG`, `INFO`, `WARNING`, `ERROR` or `CRITICAL`. | | | `loglevel` | `INFO` | Logs events at this level and higher. Can be set to `DEBUG`, `INFO`, `WARNING`, `ERROR` or `CRITICAL`. | | ||||
| `nocleanup` | `False` | Cleans up temporary test directory if set to `True` during `shutdown`. | | | `nocleanup` | `False` | Cleans up temporary test directory if set to `True` during `shutdown`. | | ||||
| `noshutdown` | `False` | Does not stop bitcoind instances after `shutdown` if set to `True`. | | | `noshutdown` | `False` | Does not stop bitcoind instances after `shutdown` if set to `True`. | | ||||
| `num_nodes` | `1` | Sets the number of initialized bitcoind processes. | | | `num_nodes` | `1` | Sets the number of initialized bitcoind processes. | | ||||
| `perf` | False | Profiles running nodes with `perf` for the duration of the test if set to `True`. | | | `perf` | False | Profiles running nodes with `perf` for the duration of the test if set to `True`. | | ||||
| `rpc_timeout` | `60` | Sets the RPC server timeout for the underlying bitcoind processes. | | | `rpc_timeout` | `60` | Sets the RPC server timeout for the underlying bitcoind processes. | | ||||
| `setup_clean_chain` | `False` | Initializes a 200-block-long chain by default. If set to `True`, initialize an empty chain. | | | `setup_clean_chain` | `False` | Initializes a 200-block-long chain by default. If set to `True`, initialize an empty chain. | | ||||
| `randomseed` | Random Integer | `TestShell.options.randomseed` is a member of `TestShell` which can be accessed during a test to seed a random generator. User can override default with a constant value for reproducible test runs. | | | `randomseed` | Random Integer | `TestShell.options.randomseed` is a member of `TestShell` which can be accessed during a test to seed a random generator. User can override default with a constant value for reproducible test runs. | | ||||
| `supports_cli` | `False` | Whether the bitcoin-cli utility is compiled and available for the test. | | | `supports_cli` | `False` | Whether the ecash-cli utility is compiled and available for the test. | | ||||
| `tmpdir` | `"/var/folders/.../"` | Sets directory for test logs. Will be deleted upon a successful test run unless `nocleanup` is set to `True` | | | `tmpdir` | `"/var/folders/.../"` | Sets directory for test logs. Will be deleted upon a successful test run unless `nocleanup` is set to `True` | | ||||
| `trace_rpc` | `False` | Logs all RPC calls if set to `True`. | | | `trace_rpc` | `False` | Logs all RPC calls if set to `True`. | | ||||
| `usecli` | `False` | Uses the bitcoin-cli interface for all bitcoind commands instead of directly calling the RPC server. Requires `supports_cli`. | | | `usecli` | `False` | Uses the ecash-cli interface for all bitcoind commands instead of directly calling the RPC server. Requires `supports_cli`. | |