github.com/git-lfs/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  ```