Merge bitcoin/bitcoin#33546: test: add functional test for TestShell (matching doc example)

57f7c68821 test: add functional test for `TestShell` (matching doc example) (Sebastian Falbesoner)
53874f7934 doc: test: update TestShell example instructions/options (Sebastian Falbesoner)

Pull request description:

  This PR adds a functional framework test for the `TestShell` class. The primary motivation for this is to avoid that the example instructions for the interactive Python shell in `test-shell.md` get outdated or broken without noticing, a problem we had already several times in the past (see #26520, #27906, #31415). Having a copy is still not perfect, as docs and functional test have to be kept in sync, but I don't expect this to be a problem in practice, assuming the hint in the functional test comment is hopefully noticed if changes are made.

  Alternatively, the example instructions in `test-shell.md` could be removed with a hint to the functional test (I tend to prefer to keep the docs as-is though, showing the full REPL interaction).

  The first commit contain two small removal fix-ups in `test-shell.md` regarding the result of the `createwallet` RPC call and the mentioning of the `noshutdown` option that was removed earlier (see #31620). Could be backported to v30.

ACKs for top commit:
  brunoerg:
    ACK 57f7c68821
  stratospher:
    ACK 57f7c68.
  pinheadmz:
    ACK 57f7c68821

Tree-SHA512: 25c35af46b742bbefce7838708437529bbf613fa3d1f0fba590cacef0acdde82b3a78c7a01459c73eaac26ce3f1041e54092d098f0fc94a8c76ac0b4f4970338

test/functional/feature_framework_testshell.py

@@ -0,0 +1,47 @@
+#!/usr/bin/env python3
+# Copyright (c) The Bitcoin Core developers
+# Distributed under the MIT software license, see the accompanying
+# file COPYING or http://www.opensource.org/licenses/mit-license.php.
+"""Tests for the `TestShell` submodule."""
+
+from decimal import Decimal
+from pathlib import Path
+
+# Note that we need to import from functional test framework modules
+# *after* extending the Python path via sys.path.insert(0, ...) below,
+# in order to work with the full symlinked (unresolved) path within the
+# build directory (usually ./build/test/functional).
+
+
+# Test matching the minimal example from the documentation. Should be kept
+# in sync with the interactive shell instructions ('>>> ') in test-shell.md.
+def run_testshell_doc_example(functional_tests_dir):
+    import sys
+    sys.path.insert(0, functional_tests_dir)
+    from test_framework.test_shell import TestShell
+    from test_framework.util import assert_equal
+
+    test = TestShell().setup(num_nodes=2, setup_clean_chain=True)
+    try:
+        assert test is not None
+        test2 = TestShell().setup()
+        assert test2 is None  # TODO: check for "TestShell is already running!" output to stdout
+        assert_equal(test.nodes[0].getblockchaininfo()["blocks"], 0)
+        if test.is_wallet_compiled():
+            res = test.nodes[0].createwallet('default')
+            assert_equal(res, {'name': 'default'})
+            address = test.nodes[0].getnewaddress()
+            res = test.generatetoaddress(test.nodes[0], 101, address)
+            assert_equal(len(res), 101)
+            test.sync_blocks()
+            assert_equal(test.nodes[1].getblockchaininfo()["blocks"], 101)
+            assert_equal(test.nodes[0].getbalance(), Decimal('50.0'))
+            test.nodes[0].log.info("Successfully mined regtest chain!")
+    finally:
+        test.shutdown()
+        test.reset()
+        assert test.num_nodes is None
+
+
+if __name__ == "__main__":
+    run_testshell_doc_example(str(Path(__file__).parent))

test/functional/test-shell.md

@@ -97,7 +97,7 @@ rewards to a wallet address owned by the mining node.
 
 ```
 >>> test.nodes[0].createwallet('default')
-{'name': 'default', 'warning': 'Empty string given as passphrase, wallet will not be encrypted.'}
+{'name': 'default'}
 >>> address = test.nodes[0].getnewaddress()
 >>> test.generatetoaddress(test.nodes[0], 101, address)
 ['2b98dd0044aae6f1cca7f88a0acf366a4bfe053c7f7b00da3c0d115f03d67efb', ...
@@ -179,7 +179,6 @@ can be called after the TestShell is shut down.
 | `coveragedir` | `None` | Records bitcoind RPC test coverage into this directory if set. |
 | `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`. |
-| `noshutdown` | `False` | Does not stop bitcoind instances after `shutdown` if set to `True`. |
 | `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`. |
 | `rpc_timeout` | `60` | Sets the RPC server timeout for the underlying bitcoind processes. |

test/functional/test_runner.py

@@ -362,6 +362,7 @@ BASE_SCRIPTS = [
     'rpc_getdescriptorinfo.py',
     'rpc_mempool_info.py',
     'rpc_help.py',
+    'feature_framework_testshell.py',
     'tool_rpcauth.py',
     'p2p_handshake.py',
     'p2p_handshake.py --v2transport',