From 986aa7f17e363128856e51efb34c878e0563c509 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Sat, 14 May 2005 00:25:06 -0700 Subject: [PATCH] [PATCH 2/2] Test framework documentation. This adds instruction for running tests, and writing new tests. Signed-off-by: Junio C Hamano Updated to the new tidied up output style. Signed-off-by: Petr Baudis --- t/README | 174 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 174 insertions(+) create mode 100644 t/README diff --git a/t/README b/t/README new file mode 100644 index 000000000..fce19e7ff --- /dev/null +++ b/t/README @@ -0,0 +1,174 @@ +Core GIT Tests +============== + +This directory holds many test scripts for core GIT tools. The +first part of this short document describes how to run the tests +and read their output. + +When fixing the tools or adding enhancements, you are strongly +encouraged to add tests in this directory to cover what you are +trying to fix or enhance. The later part of this short document +describes how your test scripts should be organized. + + +Running Tests +------------- + +The easiest way to run tests is to say "make". This runs all +the tests. + + *** t0000-basic.sh *** + * ok 1: .git/objects should be empty after git-init-db in an empty repo. + * ok 2: .git/objects should have 256 subdirectories. + * ok 3: git-update-cache without --add should fail adding. + ... + * ok 23: no diff after checkout and git-update-cache --refresh. + * passed all 23 test(s) + *** t0100-environment-names.sh *** + * ok 1: using old names should issue warnings. + * ok 2: using old names but having new names should not issue warnings. + ... + +Or you can run each test individually from command line, like +this: + + $ sh ./t0500-ls-files.sh + * ok 1: git-update-cache --add to add various paths. + * ok 2: git-ls-files -k to show killed files. + * ok 3: validate git-ls-files -k output. + * passed all 3 test(s) + +You can pass --verbose (or -v), --debug (or -d), and --immediate +(or -i) command line argument to the test. + +--verbose:: + This makes the test more verbose. Specifically, the + command being run and their output if any are also + output. + +--debug:: + This may help the person who is developing a new test. + It causes the command defined with test_debug to run. + +--immediate:: + This causes the test to immediately exit upon the first + failed test. + + +Writing Tests +------------- + +The test script is written as a shell script. It should start +with the standard "#!/bin/sh" with copyright notices, and an +assignment to variable 'test_description', like this: + + #!/bin/sh + # + # Copyright (c) 2005 Junio C Hamano + # + + test_description=xxx test (option --frotz) + + This test registers the following structure in the cache + and tries to run git-ls-files with option --frotz.' + +Source 'test-lib.sh' +-------------------- + +After assigning test_description, the test script should source +test-lib.sh like this: + + . ./test-lib.sh + +This test harness library does the following things: + + - If the script is invoked with command line argument --help + (or -h), it shows the test_description and exits. + + - Creates an empty test directory with an empty .git/objects + database and chdir(2) into it. This directory is 't/trash' + if you must know, but I do not think you care. + + - Defines standard test helper functions for your scripts to + use. These functions are designed to make all scripts behave + consistently when command line arguments --verbose (or -v), + --debug (or -d), and --immediate (or -i) is given. + + +End with test_done +------------------ + +Your script will be a sequence of tests, using helper functions +from the test harness library. At the end of the script, call +'test_done'. + + +Test harness library +-------------------- + +There are a handful helper functions defined in the test harness +library for your script to use. + + - test_expect_success