src/test_driver/linux-cirque/README.md

   1 # The cirque testing suite
   2
   3 Cirque simulates complex network topologies based upon docker nodes. On a single
   4 Linux machine, it can create multiple nodes with network stacks that are
   5 independent from each other. Some nodes may be connected to simulated Thread
   6 networks, others may connect to simulated BLE or WiFi.
   7
   8 In Project CHIP, cirque is used for integration tests.
   9
  10 There is a script for running cirque tests, you can find it at
  11 `scripts/tests/cirque_tests.sh`
  12
  13 ## Setting up cirque environment
  14
  15 After checkout, in your local project chip directory, run:
  16
  17 ```
  18 git submodule update --init
  19 scripts/tests/cirque_tests.sh bootstrap
  20 ```
  21
  22 It will:
  23
  24 1. Install necessary packages required by cirque,
  25
  26 2. Build `connectedhomeip/chip-cirque-device-base:latest` docker image for
  27    running devices,
  28
  29 3. Build openthread for simulating thread network.
  30
  31 > Note: Suggest using a clean checkout before running this.
  32
  33 ## Run tests
  34
  35 You can run the tests by:
  36
  37 ```
  38 scripts/tests/cirque_tests.sh run_all_tests
  39 ```
  40
  41 You can get more infomation from the terminal output (like the location of
  42 logs).
  43
  44 > Note: The container (as well as the networks) will be preserved for debugging.
  45 > You may need to clean it by yourself.
  46
  47 ## Run specific test
  48
  49 You can run a single cirque test by:
  50
  51 ```
  52 scripts/tests/cirque_tests.sh run_test <test name>
  53 ```
  54
  55 The test name is the script (`.sh`) file in `src/test_driver/linux-cirque`, like
  56 `OnOffClusterTest`.
  57
  58 For example, you can run `OnOffClusterTest` by:
  59
  60 ```
  61 scripts/tests/cirque_tests.sh run_test OnOffClusterTest
  62 ```
  63
  64 The output of the test will be written to `stdout` and `stderr`.
  65
  66 ## Specify log directory
  67
  68 To specify log directory, simplily set `LOG_DIR` variable.
  69
  70 ```
  71 export LOG_DIR=/some/log/directory
  72 scripts/tests/cirque_tests.sh run_all_tests
  73 scripts/tests/cirque_tests.sh run_test OnOffClusterTest
  74 ```
  75
  76 Or
  77
  78 ```
  79 LOG_DIR=/some/log/directory scripts/tests/cirque_tests.sh run_all_tests
  80 LOG_DIR=/some/log/directory scripts/tests/cirque_tests.sh run_test OnOffClusterTest
  81 ```