Merge pull request #8923 from obsidiansystems/test-proto

Unit test some worker protocol serializers

doc/manual/src/contributing/testing.md

@@ -16,14 +16,70 @@ You can build it yourself:
 
 ## Unit-tests
 
-The unit-tests for each Nix library (`libexpr`, `libstore`, etc..) are defined
-under `src/{library_name}/tests` using the
-[googletest](https://google.github.io/googletest/) and
-[rapidcheck](https://github.com/emil-e/rapidcheck) frameworks.
+The unit tests are defined using the [googletest] and [rapidcheck] frameworks.
+
+[googletest]: https://google.github.io/googletest/
+[rapidcheck]: https://github.com/emil-e/rapidcheck
+
+### Source and header layout
+
+> An example of some files, demonstrating much of what is described below
+>
+> ```
+> src
+> ├── libexpr
+> │   ├── value/context.hh
+> │   ├── value/context.cc
+> │   │
+> │   …
+>     └── tests
+> │       ├── value/context.hh
+> │       ├── value/context.cc
+> │       │
+> │       …
+> │
+> ├── unit-test-data
+> │   ├── libstore
+> │   │   ├── worker-protocol/content-address.bin
+> │   │   …
+> │   …
+> …
+> ```
+
+The unit tests for each Nix library (`libnixexpr`, `libnixstore`, etc..) live inside a directory `src/${library_shortname}/tests` within the directory for the library (`src/${library_shortname}`).
+
+The data is in `unit-test-data`, with one subdir per library, with the same name as where the code goes.
+For example, `libnixstore` code is in `src/libstore`, and its test data is in `unit-test-data/libstore`.
+The path to the `unit-test-data` directory is passed to the unit test executable with the environment variable `_NIX_TEST_UNIT_DATA`.
+
+> **Note**
+> Due to the way googletest works, downstream unit test executables will actually include and re-run upstream library tests.
+> Therefore it is important that the same value for `_NIX_TEST_UNIT_DATA` be used with the tests for each library.
+> That is why we have the test data nested within a single `unit-test-data` directory.
+
+### Running tests
 
 You can run the whole testsuite with `make check`, or the tests for a specific component with `make libfoo-tests_RUN`.
 Finer-grained filtering is also possible using the [--gtest_filter](https://google.github.io/googletest/advanced.html#running-a-subset-of-the-tests) command-line option, or the `GTEST_FILTER` environment variable.
 
+### Characterization testing
+
+See [below](#characterization-testing-1) for a broader discussion of characterization testing.
+
+Like with the functional characterization, `_NIX_TEST_ACCEPT=1` is also used.
+For example:
+```shell-session
+$ _NIX_TEST_ACCEPT=1 make libstore-tests-exe_RUN
+...
+[  SKIPPED ] WorkerProtoTest.string_read
+[  SKIPPED ] WorkerProtoTest.string_write
+[  SKIPPED ] WorkerProtoTest.storePath_read
+[  SKIPPED ] WorkerProtoTest.storePath_write
+...
+```
+will regenerate the "golden master" expected result for the `libnixstore` characterization tests.
+The characterization tests will mark themselves "skipped" since they regenerated the expected result instead of actually testing anything.
+
 ## Functional tests
 
 The functional tests reside under the `tests` directory and are listed in `tests/local.mk`.
@@ -138,9 +194,12 @@ This technique is to include the exact output/behavior of a former version of Ni
 For example, this technique is used for the language tests, to check both the printed final value if evaluation was successful, and any errors and warnings encountered.
 
 It is frequently useful to regenerate the expected output.
-To do that, rerun the failed test with `_NIX_TEST_ACCEPT=1`.
-(At least, this is the convention we've used for `tests/lang.sh`.
-If we add more characterization testing we should always strive to be consistent.)
+To do that, rerun the failed test(s) with `_NIX_TEST_ACCEPT=1`.
+For example:
+```bash
+_NIX_TEST_ACCEPT=1 make tests/lang.sh.test
+```
+This convention is shared with the [characterization unit tests](#characterization-testing-1) too.
 
 An interesting situation to document is the case when these tests are "overfitted".
 The language tests are, again, an example of this.