github.com/catandhorse/git-lfs@v2.5.2+incompatible/t/README.md (about) 1 # `t` 2 3 This directory contains one of the two types of tests that the Git LFS project 4 uses to protect against regression. The first, scattered in `*_test.go` files 5 throughout the repository are _unit tests_, and written in Go, designed to 6 uncover failures at the unit level. 7 8 The second kind--and the one contained in this directory--are _integration 9 tests_, which are designed to exercise Git LFS in an end-to-end fashion, 10 running the `git`, and `git-lfs` binaries, along with a mock Git server. 11 12 You can run all tests in this directory with any of the following: 13 14 ```ShellSession 15 $ make 16 $ make test 17 $ make PROVE_EXTRA_ARGS=-j9 test 18 ``` 19 20 Or run a single test (for example, `t-checkout.sh`) by any of the following: 21 22 ```ShellSession 23 $ make ./t-checkout.sh 24 $ make PROVE_EXTRA_ARGS=-v ./t-checkout.sh 25 $ ./t-checkout.sh 26 ``` 27 28 Alternatively, one can run a selection of tests (via explicitly listing them or 29 making use of the built-in shell globbing) by any of the following: 30 31 ```ShellSession 32 $ make ./t-*.sh 33 $ make PROVE_EXTRA_ARGS=-j9 ./t-*.sh 34 $ ./t-*.sh 35 ``` 36 37 ## Test File(s) 38 39 There are a few important kinds of files to know about in the `t` directory: 40 41 - `cmd/`: contains the source code of binaries that are useful during test 42 time, like the mocked Git server, or the test counting binary. For more about 43 the contents of this directory, see [test lifecycle](#test-lifecycle) below. 44 45 The file `t/cmd/testutils.go` is automatically linked and included during the 46 build process of each file in `cmd`. 47 48 - `fixtures/`: contains shell scripts that load fixture repositories useful for 49 testing against. 50 51 - `t-*.sh`: file(s) containing zero or more tests, typically related to 52 a similar topic (c.f,. `t/t-push.sh`, `t/t-pull.sh`, etc.) 53 54 - `testenv.sh`: loads environment variables useful during tests. This file is 55 sourced by `testlib.sh`. 56 57 - `testhelpers.sh`: loads shell functions useful during tests, like 58 `setup_remote_repo`, and `clone_repo`. 59 60 - `testlib.sh`: loads the `begin_test`, `end_test`, and similar functions 61 useful for instantiating a particular test. 62 63 ## Test Lifecycle 64 65 When a test is run, the following occurs, in order: 66 67 1. Missing test binaries are compiled into the `bin` directory in the 68 repository root. Note: this does _not_ include the `git-lfs` binary, which 69 is re-compiled via `script/boostrap`. 70 71 2. An integration server is started by either (1) the `Makefile` or (2) the 72 `cmd/lfstest-count-test.go` program, which keeps track of the number of 73 running tests and starts an integration server any time the number of active 74 tests goes from `0` to `1`, and stops the server when it goes from `n` to 75 `0`. 76 77 3. After sourcing `t/testlib.sh` (& loading `t/testenv.sh`), each test is run 78 in sequence per file. (In other words, multiple test files can be run in 79 parallel, but the tests in a single file are run in sequence.) 80 81 4. An individual test will finish, and (if running under `prove`) another will 82 be started in its place. Once all tests are done, `t/test_count` will go to 83 `0`, and the test server will be torn down. 84 85 ## Test Environment 86 87 There are a few environment variables that you can set to change the test suite 88 behavior: 89 90 * `GIT_LFS_TEST_DIR=path` - This sets the directory that is used as the current 91 working directory of the tests. By default, this will be in your temp dir. It's 92 recommended that this is set to a directory outside of any Git repository. 93 94 * `KEEPTRASH=1` - This will leave the local repository data in a `tmp` directory 95 and the remote repository data in `test/remote`. 96 97 Also ensure that your `noproxy` environment variable contains `127.0.0.1` host, 98 to allow git commands to reach the local Git server `lfstest-gitserver`. 99 100 ## Writing new tests 101 102 A new test file should be named `t/t-*.sh`, where `*` is the topic of Git LFS 103 being tested. It should look as follows: 104 105 ```bash 106 #!/usr/bin/env bash 107 108 . "$(dirname "$0")/testlib.sh" 109 110 begin_test "my test" 111 ( 112 set -e 113 114 # ... 115 ) 116 end_test 117 ```