From b19a9ff56da5ec119bfc2420865f58249ee4e7c6 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Wed, 1 Nov 2023 06:52:56 +0000 Subject: [PATCH] ;doc:tests:readme --- hledger/test/README.md | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/hledger/test/README.md b/hledger/test/README.md index a303e9178..8eb47cfae 100644 --- a/hledger/test/README.md +++ b/hledger/test/README.md @@ -12,9 +12,19 @@ The rest of the files here are functional tests, run with [shelltestrunner]. These test the hledger CLI and (indirectly) the hledger-lib package. They are organised roughly by [component]. -Older test files are in shelltestrunner's [format 1]; -newer ones use [format 3] (preferred). -Some tests invoke unix commands so will not run in a Windows CMD shell. +shelltestrunner's latest [format 3] is preferred, +though some tests may still be using the older [format 1]. +Each command line (beginning with `$`) is a single test, +which usually reads input from a preceding `<` section, +and is followed by expected output, +and any non-standard error output (`>2`) or exit code (`>=`). + +Additionally, each test is preceded by a descriptive comment (`#`). +This should begin with an Emacs outshine heading marker (` ** `), +useful for folding and browsing tests in Emacs, +and a test number (`1. `), useful for running individual tests. + +A few tests invoke unix commands; these won't run in a Windows CMD shell. [Developer docs > TESTS]: https://hledger.org/TESTS.html [component]: https://hledger.org/CONTRIBUTING.html#components @@ -41,9 +51,9 @@ These are the most important: - ``-w `stack exec -- which hledger` `` ensures you are testing the hledger executable that was just built. - `-j16` runs tests in parallel which is much faster. -Run only the tests matching a regular expression: +Run only the tests matching a regular expression (`balance-assertions:.*19` in this case):) - $ COLUMNS=80 shelltest --execdir -w `stack exec -- which hledger` tests -i balance-assertions.*19 + $ make functest-balance-assertions.*19 :hledger/test/journal/balance-assertions.test:19: [OK] Test Cases Total