github.com/pingcap/br@v5.3.0-alpha.0.20220125034240-ec59c7b6ce30+incompatible/tests/README.md (about)

     1  # Unit tests
     2  
     3  Unit tests (the `*_test.go` files inside the source directory) should *never* rely on external
     4  programs.
     5  
     6  Run `make test` to execute all unit tests.
     7  
     8  To run a specific test, pass `ARGS` into `make test` like
     9  
    10  ```sh
    11  make test ARGS='github.com/pingcap/br/pkg/cdclog --test.v --check.v --check.f TestColumn'
    12  #               ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    13  #                which package to test            more extra test flags
    14  ```
    15  
    16  You can also run unit tests directly via `go test` like:
    17  
    18  ```sh
    19  make failpoint-enable
    20  
    21  go test github.com/pingcap/br/pkg/cdclog --test.v --check.v --check.f TestColumn
    22  
    23  make failpoint-disable
    24  ```
    25  
    26  but note that:
    27  
    28  * failpoints must be toggled manually
    29  
    30  # Integration tests
    31  
    32  This folder contains all tests which relies on external processes such as TiDB.
    33  
    34  ## Preparations
    35  
    36  1. The following 9 executables must be copied or linked into these locations:
    37  
    38      * `bin/tidb-server`
    39      * `bin/tikv-server`
    40      * `bin/pd-server`
    41      * `bin/pd-ctl`
    42      * `bin/go-ycsb`
    43      * `bin/minio`
    44      * `bin/mc`
    45      * `bin/tiflash`
    46      * `bin/cdc`
    47      * `bin/tikv-importer`
    48  
    49      The versions must be ≥2.1.0.
    50  
    51      What's more, there must be dynamic link library for TiFlash, see make target `bin` to learn more.
    52      You can install most of dependencies by running `download_tools.sh`.
    53  
    54  2. The following programs must be installed:
    55  
    56      * `mysql` (the CLI client)
    57      * `curl`
    58      * `openssl`
    59      * `wget`
    60      * `lsof`
    61  
    62  3. The user executing the tests must have permission to create the folder
    63      `/tmp/backup_restore_test`. All test artifacts will be written into this folder.
    64  
    65  If you have docker installed, you can skip step 1 and step 2 by running
    66  `tests/up.sh --pull-images` to build and run a testing Docker container.
    67  
    68  ## Running
    69  
    70  Run `make integration_test` to execute the integration tests. This command will
    71  
    72  1. Build `br`
    73  2. Check that all 9 required executables and `br` executable exist
    74  3. Execute `tests/run.sh`
    75  4. To start cluster with tiflash, please run `TIFLASH=1 tests/run.sh`
    76  
    77  If the first two steps are done before, you could also run `tests/run.sh` directly.
    78  This script will
    79  
    80  1. Start PD, TiKV and TiDB in background with local storage
    81  2. Find out all `tests/*/run.sh` and run it
    82  
    83  Run `tests/run.sh --debug` to pause immediately after all servers are started.
    84  
    85  After executing the tests, run `make coverage` to get a coverage report at
    86  `/tmp/backup_restore_test/all_cov.html`.
    87  
    88  ## Writing new tests
    89  
    90  New integration tests can be written as shell scripts in `tests/TEST_NAME/run.sh`.
    91  The script should exit with a nonzero error code on failure.
    92  
    93  Several convenient commands are provided:
    94  
    95  * `run_sql <SQL>` — Executes an SQL query on the TiDB database
    96  * `run_lightning [CONFIG]` — Starts `tidb-lightning` using `tests/TEST_NAME/CONFIG.toml`
    97  * `check_contains <TEXT>` — Checks if the previous `run_sql` result contains the given text
    98      (in `-E` format)
    99  * `check_not_contains <TEXT>` — Checks if the previous `run_sql` result does not contain the given
   100      text (in `-E` format)