luxolus
/
open-consul
2
0
Fork 0
Code Issues 1 Pull Requests Packages Releases Wiki Activity

Document integration tests (#14391)

This commit is contained in:
Luke Kysow 2022-09-13 10:00:02 -07:00 committed by GitHub
parent cfcd9f2a2c
commit 8e4e0c23aa
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 52 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/README.md
View File

@ -35,6 +35,10 @@ be found in the public [user documentation].
Also see the [FAQ](./faq.md).
## Other Docs
1. [Integration Tests](../test/integration/connect/envoy/README.md)
## Important Directories
Most top level directories contain Go source code. The directories listed below

48
test/integration/connect/envoy/README.md Normal file
View File

@ -0,0 +1,48 @@
# Envoy Integration Tests
## Overview
These tests validate that Consul is configuring Envoy correctly. They set up various scenarios using Docker containers and then run
[Bats](https://github.com/sstephenson/bats) (a Bash test framework) tests to validate the expected results.
## Running Tests
To run the tests locally, `cd` into the root of the repo and run:
```console
make test-envoy-integ
```
To run a specific test, run:
```console
make test-envoy-integ GO_TEST_FLAGS="-run TestEnvoy/case-basic"
```
Where `case-basic` can be replaced by any directory name from this directory.
## How Do These Tests Work
1. The tests are all run through Go test via the `main_test.go` file. Each directory prefixed by `case-` is a subtest, for example,
`TestEnvoy/case-basic` and `TestEnvoy/case-wanfed-gw`.
2. The real framework for this test suite lives in `run-tests.sh`. Under the hood, `main_test.go` just runs `run-tests.sh` with
various arguments.
3. The tests use your local code by building a Docker image from your local directory just before executing.
4. The tests run Docker containers connected by a shared Docker network. All tests have at least one Consul server running and then
depending on the test case they will spin up additional services or gateways. Some tests run multiple Consul servers to test
multi-DC setups.
5. At a high level, tests are set up by executing the `setup.sh` script in each directory. This script uses helper functions
defined in `helpers.bash`. Once the test case is set up, the validations in `verify.bats` are run.
6. In CI, the tests are executed against different Envoy versions and with both `XDS_TARGET=client` and `XDS_TARGET=server`.
If set to `client`, a Consul server and client are run, and services are registered against the client. If set to `server`,
only a Consul server is run, and services are registered against the server. By default, `XDS_TARGET` is set to `server`.
See [this comment](https://github.com/hashicorp/consul/blob/70bb6a2abdbc5ed4a6e728e8da243c5394a631d1/test/integration/connect/envoy/run-tests.sh#L178-L212) for more information.
## Investigating Test Failures
* When tests fail in CI, logs and additional debugging data are available in the artifacts of the test run.
* You can re-run the tests locally by running `make test-envoy-integ GO_TEST_FLAGS="-run TestEnvoy/<case-directory>"` where `<case-directory>` is
replaced with the name of the directory, e.g. `case-basic`.
* Locally, all the logs of the failed test will be available in `workdir` in this directory.
* You can run with `DEBUG=1` to print out all the commands being run, e.g. `DEBUG=1 make test-envoy-integ GO_TEST_FLAGS="-run TestEnvoy/case-basic"`.
* If you want to prevent the Docker containers from being spun down after test failure, add a `sleep 9999` to the `verify.bats` test case that's failing.