Skip to content

Commit

Permalink
doc: Improve test READMEs
Browse files Browse the repository at this point in the history
  • Loading branch information
fjahr committed Sep 26, 2019
1 parent 3ce8298 commit 43e7d57
Show file tree
Hide file tree
Showing 2 changed files with 50 additions and 18 deletions.
42 changes: 29 additions & 13 deletions src/test/README.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,15 @@
# Unit tests

The sources in this directory are unit test cases. Boost includes a
unit testing framework, and since Bitcoin Core already uses Boost, it makes
sense to simply use this framework rather than require developers to
configure some other framework (we want as few impediments to creating
unit tests as possible).

The build system is set up to compile an executable called `test_bitcoin`
that runs all of the unit tests. The main source file is called
`setup_common.cpp`.

### Compiling/running unit tests

Unit tests will be automatically compiled if dependencies were met in `./configure`
Expand All @@ -12,7 +24,7 @@ to run the bitcoind tests.

To add more bitcoind tests, add `BOOST_AUTO_TEST_CASE` functions to the existing
.cpp files in the `test/` directory or add new .cpp files that
implement new BOOST_AUTO_TEST_SUITE sections.
implement new `BOOST_AUTO_TEST_SUITE` sections.

To run the bitcoin-qt tests manually, launch `src/qt/test/test_bitcoin-qt`

Expand All @@ -32,20 +44,24 @@ example, to run just the getarg_tests verbosely:

Run `test_bitcoin --help` for the full list.

### Note on adding test cases

The sources in this directory are unit test cases. Boost includes a
unit testing framework, and since bitcoin already uses boost, it makes
sense to simply use this framework rather than require developers to
configure some other framework (we want as few impediments to creating
unit tests as possible).
### Adding test cases

The build system is setup to compile an executable called `test_bitcoin`
that runs all of the unit tests. The main source file is called
setup_common.cpp. To add a new unit test file to our test suite you need
To add a new unit test file to our test suite you need
to add the file to `src/Makefile.test.include`. The pattern is to create
one test file for each class or source file for which you want to create
unit tests. The file naming convention is `<source_filename>_tests.cpp`
unit tests. The file naming convention is `<source_filename>_tests.cpp`
and such files should wrap their tests in a test suite
called `<source_filename>_tests`. For an example of this pattern,
examine `uint256_tests.cpp`.
see `uint256_tests.cpp`.

### Logging and debugging in unit tests

To write to logs from unit tests you need to use specific message methods
provided by Boost. The simplest is `BOOST_TEST_MESSAGE`.

For debugging you can launch the test_bitcoin executable with `gdb`or `lldb` and
start debugging, just like you would with bitcoind:

```bash
gdb src/test/test_bitcoin
```
26 changes: 21 additions & 5 deletions test/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -136,8 +136,10 @@ killall bitcoind

##### Test logging

The tests contain logging at different levels (debug, info, warning, etc). By
default:
The tests contain logging at five different levels (DEBUG, INFO, WARNING, ERROR
and CRITICAL). From within your functional tests you can log to these different
levels using the logger included in the test_framework, e.g.
`self.log.debug(object)`. By default:

- when run through the test_runner harness, *all* logs are written to
`test_framework.log` and no logs are output to the console.
Expand Down Expand Up @@ -182,18 +184,32 @@ call methods that interact with the bitcoind nodes-under-test.
If further introspection of the bitcoind instances themselves becomes
necessary, this can be accomplished by first setting a pdb breakpoint
at an appropriate location, running the test to that point, then using
`gdb` to attach to the process and debug.
`gdb` (or `lldb` on macOS) to attach to the process and debug.

For instance, to attach to `self.node[1]` during a run:
For instance, to attach to `self.node[1]` during a run you can get
the pid of the node within `pdb`.

```
(pdb) self.node[1].process.pid
```

Alternatively, you can find the pid by inspecting the temp folder for the specific test
you are running. The path to that folder is printed at the beginning of every
test run:

```bash
2017-06-27 14:13:56.686000 TestFramework (INFO): Initializing test directory /tmp/user/1000/testo9vsdjo3
```

use the directory path to get the pid from the pid file:
Use the path to find the pid file in the temp folder:

```bash
cat /tmp/user/1000/testo9vsdjo3/node1/regtest/bitcoind.pid
```

Then you can use the pid to start `gdb`:

```bash
gdb /home/example/bitcoind <pid>
```

Expand Down

0 comments on commit 43e7d57

Please sign in to comment.