diff --git a/images/integration-testing-setup.png b/images/integration-testing-setup.png new file mode 100644 index 0000000000000000000000000000000000000000..8d59e14b6a61cad794f499b25258c179cd057519 Binary files /dev/null and b/images/integration-testing-setup.png differ diff --git a/tools/integration-tests/README.md b/tools/integration-tests/README.md index 7fd231ccf91a1c43e90c2faec01f3d8bd2db5d75..6a93d087413088ff81e4517cc88850f796dbc34b 100644 --- a/tools/integration-tests/README.md +++ b/tools/integration-tests/README.md @@ -1,7 +1,53 @@ # Integration tests with Docker + +Running the integration tests spins up a GoShimmer network within Docker as schematically shown in the figure above. +`N` defines the number of `peer_replicas` and can be specified when running the network. +The peers can communicate freely within the Docker network and this is exactly how the tests are run using the `tester` container. +Test can be written in regular Go style while the framework provides convenience functions to access a specific peer's web API or logs. +The visualizer, `master_peer's` dashboard and web API are reachable from the host system on the respective ports. + +The different containers (`entry_node`, `peer_master`, `peer_replica`) load separate config files that can be modified as necessary, respectively. + +## How to run +Prerequisites: +- Docker +- Docker compose + +``` +# Mac & Linux +./runTests.sh +``` +The tests produce `*.log` files for every peer in the `logs` folder after every run. + +Currently, the integration tests are configured to run on every push to GitHub with `peer_replica=5`. +The logs of every peer are stored as artifacts and can be downloaded for closer inspection once the job finishes. + +## Creating tests +Tests can be written in regular Go style. Each tested component should reside in its own test file in `tester/tests`. +`main_test` with its `TestMain` function is executed before any test in the package and initializes the integration test framework. + + +## Use as development tool +Using a standalone throwaway Docker network can be really helpful as a development tool as well. + +Reachable from the host system +- visualizer: http://localhost:9000 +- `master_peer's` dashboard: http: http://localhost:8081 +- `master_peer's` web API: http: http://localhost:8080 + +It is therefore possible to send messages to the local network via the `master_peer` and observe log messages either +via `docker logs --follow CONTAINER` or by starting the Docker network without the `-d` option, as follows. + +``` +docker-compose -f docker-compose.yml up --scale peer_replica=5 + +# 1. test manually with master_peer + +# 2. or run in separate terminal window +docker-compose -f tester/docker-compose.yml up --exit-code-from tester ``` -docker-compose up --scale peer_replica=2 -``` \ No newline at end of file +Sometimes when changing files, either in the tests or in GoShimmer, Docker does not detect the changes on a rebuild. +Then the option `--build` needs to be used with `docker-compose`. \ No newline at end of file diff --git a/tools/integration-tests/runTests.sh b/tools/integration-tests/runTests.sh index 3635cb69b6f133dca176eb7ed248c8bbd837c74b..338276976cd3369458d02b54cf23bd93e277ee9d 100755 --- a/tools/integration-tests/runTests.sh +++ b/tools/integration-tests/runTests.sh @@ -8,7 +8,7 @@ fi REPLICAS=$1 echo "Build GoShimmer Docker network" -docker-compose -f docker-compose.yml up -d --scale peer_replica=$1 +docker-compose -f docker-compose.yml up -d --scale peer_replica=$REPLICAS if [ $? -ne 0 ]; then { echo "Failed, aborting." ; exit 1; } fi echo "Dispay containers"