github.com/Oyster-zx/tendermint@v0.34.24-fork/test/e2e/README.md (about)

     1  # End-to-End Tests
     2  
     3  Spins up and tests Tendermint networks in Docker Compose based on a testnet manifest. To run the CI testnet:
     4  
     5  ```sh
     6  make
     7  ./build/runner -f networks/ci.toml
     8  ```
     9  
    10  This creates and runs a testnet named `ci` under `networks/ci/` (determined by the manifest filename).
    11  
    12  ## Testnet Manifests
    13  
    14  Testnets are specified as TOML manifests. For an example see [`networks/ci.toml`](networks/ci.toml), and for documentation see [`pkg/manifest.go`](pkg/manifest.go).
    15  
    16  ## Random Testnet Generation
    17  
    18  Random (but deterministic) combinations of testnets can be generated with `generator`:
    19  
    20  ```sh
    21  ./build/generator -d networks/generated/
    22  
    23  # Split networks into 8 groups (by filename)
    24  ./build/generator -g 8 -d networks/generated/
    25  ```
    26  
    27  Multiple testnets can be run with the `run-multiple.sh` script:
    28  
    29  ```sh
    30  ./run-multiple.sh networks/generated/gen-group3-*.toml
    31  ```
    32  
    33  ## Test Stages
    34  
    35  The test runner has the following stages, which can also be executed explicitly by running `./build/runner -f <manifest> <stage>`:
    36  
    37  * `setup`: generates configuration files.
    38  
    39  * `start`: starts Docker containers.
    40  
    41  * `load`: generates a transaction load against the testnet nodes.
    42  
    43  * `perturb`: runs any requested perturbations (e.g. node restarts or network disconnects).
    44  
    45  * `wait`: waits for a few blocks to be produced, and for all nodes to catch up to it.
    46  
    47  * `test`: runs test cases in `tests/` against all nodes in a running testnet.
    48  
    49  * `stop`: stops Docker containers.
    50  
    51  * `cleanup`: removes configuration files and Docker containers/networks.
    52  
    53  Auxiliary commands:
    54  
    55  * `logs`: outputs all node logs.
    56  
    57  * `tail`: tails (follows) node logs until cancelled.
    58  
    59  ## Tests
    60  
    61  Test cases are written as normal Go tests in `tests/`. They use a `testNode()` helper which executes each test as a parallel subtest for each node in the network.
    62  
    63  ### Running Manual Tests
    64  
    65  To run tests manually, set the `E2E_MANIFEST` environment variable to the path of the testnet manifest (e.g. `networks/ci.toml`) and run them as normal, e.g.:
    66  
    67  ```sh
    68  ./build/runner -f networks/ci.toml start
    69  E2E_MANIFEST=networks/ci.toml go test -v ./tests/...
    70  ```
    71  
    72  Optionally, `E2E_NODE` specifies the name of a single testnet node to test.
    73  
    74  These environment variables can also be specified in `tests/e2e_test.go` to run tests from an editor or IDE:
    75  
    76  ```go
    77  func init() {
    78  	// This can be used to manually specify a testnet manifest and/or node to
    79  	// run tests against. The testnet must have been started by the runner first.
    80  	os.Setenv("E2E_MANIFEST", "networks/ci.toml")
    81  	os.Setenv("E2E_NODE", "validator01")
    82  }
    83  ```
    84  
    85  ### Debugging Failures
    86  
    87  If a command or test fails, the runner simply exits with an error message and
    88  non-zero status code. The testnet is left running with data in the testnet
    89  directory, and can be inspected with e.g. `docker ps`, `docker logs`, or
    90  `./build/runner -f <manifest> logs` or `tail`. To shut down and remove the
    91  testnet, run `./build/runner -f <manifest> cleanup`.
    92  
    93  If the standard `log_level` is not detailed enough (e.g. you want "debug" level
    94  logging for certain modules), you can change it in the manifest file.
    95  
    96  Each node exposes a [pprof](https://golang.org/pkg/runtime/pprof/) server. To
    97  find out the local port, run `docker port <NODENAME> 6060 | awk -F: '{print
    98  $2}'`. Then you may perform any queries supported by the pprof tool. Julia
    99  Evans has a [great
   100  post](https://jvns.ca/blog/2017/09/24/profiling-go-with-pprof/) on this
   101  subject.
   102  
   103  ```bash
   104  export PORT=$(docker port full01 6060 | awk -F: '{print $2}')
   105  
   106  go tool pprof http://localhost:$PORT/debug/pprof/goroutine
   107  go tool pprof http://localhost:$PORT/debug/pprof/heap
   108  go tool pprof http://localhost:$PORT/debug/pprof/threadcreate
   109  go tool pprof http://localhost:$PORT/debug/pprof/block
   110  go tool pprof http://localhost:$PORT/debug/pprof/mutex
   111  ```
   112  
   113  ## Enabling IPv6
   114  
   115  Docker does not enable IPv6 by default. To do so, enter the following in
   116  `daemon.json` (or in the Docker for Mac UI under Preferences → Docker Engine):
   117  
   118  ```json
   119  {
   120    "ipv6": true,
   121    "fixed-cidr-v6": "2001:db8:1::/64"
   122  }
   123  ```
   124  
   125  ## Benchmarking Testnets
   126  
   127  It is also possible to run a simple benchmark on a testnet. This is done through the `benchmark` command. This manages the entire process: setting up the environment, starting the test net, waiting for a considerable amount of blocks to be used (currently 100), and then returning the following metrics from the sample of the blockchain:
   128  
   129  - Average time to produce a block
   130  - Standard deviation of producing a block
   131  - Minimum and maximum time to produce a block
   132  
   133  ## Running Individual Nodes
   134  
   135  The E2E test harness is designed to run several nodes of varying configurations within docker. It is also possible to run a single node in the case of running larger, geographically-dispersed testnets. To run a single node you can either run:
   136  
   137  **Built-in**
   138  
   139  ```bash
   140  make node
   141  tendermint init validator
   142  TMHOME=$HOME/.tendermint ./build/node ./node/built-in.toml
   143  ```
   144  
   145  To make things simpler the e2e application can also be run in the tendermint binary
   146  by running
   147  
   148  ```bash
   149  tendermint start --proxy-app e2e
   150  ```
   151  
   152  However this won't offer the same level of configurability of the application.
   153  
   154  **Socket**
   155  
   156  ```bash
   157  make node
   158  tendermint init validator
   159  tendermint start
   160  ./build/node ./node.socket.toml
   161  ```
   162  
   163  Check `node/config.go` to see how the settings of the test application can be tweaked.