212 lines
6.7 KiB
Plaintext
212 lines
6.7 KiB
Plaintext
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 in an empty repo.
|
|
* ok 2: .git/objects should have 256 subdirectories.
|
|
* ok 3: git-update-index without --add should fail adding.
|
|
...
|
|
* ok 23: no diff after checkout and git-update-index --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 ./t3001-ls-files-killed.sh
|
|
* ok 1: git-update-index --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.
|
|
|
|
|
|
Naming Tests
|
|
------------
|
|
|
|
The test files are named as:
|
|
|
|
tNNNN-commandname-details.sh
|
|
|
|
where N is a decimal digit.
|
|
|
|
First digit tells the family:
|
|
|
|
0 - the absolute basics and global stuff
|
|
1 - the basic commands concerning database
|
|
2 - the basic commands concerning the working tree
|
|
3 - the other basic commands (e.g. ls-files)
|
|
4 - the diff commands
|
|
5 - the pull and exporting commands
|
|
6 - the revision tree commands (even e.g. merge-base)
|
|
7 - the porcelainish commands concerning the working tree
|
|
8 - the porcelainish commands concerning forensics
|
|
9 - the git tools
|
|
|
|
Second digit tells the particular command we are testing.
|
|
|
|
Third digit (optionally) tells the particular switch or group of switches
|
|
we are testing.
|
|
|
|
If you create files under t/ directory (i.e. here) that is not
|
|
the top-level test script, never name the file to match the above
|
|
pattern. The Makefile here considers all such files as the
|
|
top-level test script and tries to run all of them. A care is
|
|
especially needed if you are creating a common test library
|
|
file, similar to test-lib.sh, because such a library file may
|
|
not be suitable for standalone execution.
|
|
|
|
|
|
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 <message> <script>
|
|
|
|
This takes two strings as parameter, and evaluates the
|
|
<script>. If it yields success, test is considered
|
|
successful. <message> should state what it is testing.
|
|
|
|
Example:
|
|
|
|
test_expect_success \
|
|
'git-write-tree should be able to write an empty tree.' \
|
|
'tree=$(git-write-tree)'
|
|
|
|
- test_expect_failure <message> <script>
|
|
|
|
This is the opposite of test_expect_success. If <script>
|
|
yields success, test is considered a failure.
|
|
|
|
Example:
|
|
|
|
test_expect_failure \
|
|
'git-update-index without --add should fail adding.' \
|
|
'git-update-index should-be-empty'
|
|
|
|
- test_debug <script>
|
|
|
|
This takes a single argument, <script>, and evaluates it only
|
|
when the test script is started with --debug command line
|
|
argument. This is primarily meant for use during the
|
|
development of a new test script.
|
|
|
|
- test_done
|
|
|
|
Your test script must have test_done at the end. Its purpose
|
|
is to summarize successes and failures in the test script and
|
|
exit with an appropriate error code.
|
|
|
|
|
|
Tips for Writing Tests
|
|
----------------------
|
|
|
|
As with any programming projects, existing programs are the best
|
|
source of the information. However, do _not_ emulate
|
|
t0000-basic.sh when writing your tests. The test is special in
|
|
that it tries to validate the very core of GIT. For example, it
|
|
knows that there will be 256 subdirectories under .git/objects/,
|
|
and it knows that the object ID of an empty tree is a certain
|
|
40-byte string. This is deliberately done so in t0000-basic.sh
|
|
because the things the very basic core test tries to achieve is
|
|
to serve as a basis for people who are changing the GIT internal
|
|
drastically. For these people, after making certain changes,
|
|
not seeing failures from the basic test _is_ a failure. And
|
|
such drastic changes to the core GIT that even changes these
|
|
otherwise supposedly stable object IDs should be accompanied by
|
|
an update to t0000-basic.sh.
|
|
|
|
However, other tests that simply rely on basic parts of the core
|
|
GIT working properly should not have that level of intimate
|
|
knowledge of the core GIT internals. If all the test scripts
|
|
hardcoded the object IDs like t0000-basic.sh does, that defeats
|
|
the purpose of t0000-basic.sh, which is to isolate that level of
|
|
validation in one place. Your test also ends up needing
|
|
updating when such a change to the internal happens, so do _not_
|
|
do it and leave the low level of validation to t0000-basic.sh.
|