github.com/juju/juju@v0.0.0-20240430160146-1752b71fcf00/tests/README.md (about)

     1  # Test Suite
     2  
     3  The following package contains the integration test suite for Juju.
     4  
     5  Tests are structured into test suites. Each suite contains a root task (akin
     6  to a package test) that will setup and run each individual test.
     7  
     8  To help break tests down, each test can have a number of subtests. Subtests
     9  are meant for individual units of work, without having to bootstrap a controller
    10  for every test. Each subtest will just `ensure` that it does have one; failing
    11  to find a suitable controller, it will create one for you.
    12  
    13  ### Example of a test suite
    14  
    15  ```sh
    16  /suites/deploy/                    # test-suite
    17                 task.sh             # root/package test (setup)
    18                 deploy_bundles.sh   # tests
    19  ```
    20  
    21  ### Example of a test
    22  
    23  ```sh
    24  run_deploy_bundles() {             # Subtest
    25  
    26  }
    27  
    28  test_deploy_bundles() {            # Test
    29      run "run_deploy_bundles"       # Run subtest
    30  }
    31  ```
    32  
    33  ## Exit codes / Success
    34  
    35  All tests will run through until the end of a test/subtest, unless it encounters
    36  a non-zero exit code. In other words, if you want to assert something passes,
    37  ensure that the command returns `exit 0`. Failure can then be detected of the
    38  inverse.
    39  
    40  ```sh
    41  echo "passes" | grep -q "passes"   # passes
    42  echo "failed" | grep -q "passes"   # fails
    43  ```
    44  
    45  ## Getting started
    46  
    47  Before running tests, you'll need to install `jq`, `yq`, `shellcheck` and `expect`:
    48  
    49  ```sh
    50  sudo snap install jq
    51  sudo snap install yq
    52  sudo snap install shellcheck
    53  sudo snap install expect
    54  ```
    55  
    56  `curl` is also required, but this should be preinstalled on most systems.
    57  
    58  The static analysis tests also require `golangci-lint`:
    59  
    60  ```
    61  go install github.com/golangci/golangci-lint/cmd/golangci-lint@v1.54.2
    62  ```
    63  
    64  To get started, it's best to quickly look at the help command from the runner.
    65  
    66  ```sh
    67  cd tests && ./main.sh -h
    68  ```
    69  
    70  Running a full sweep of the integration tests (which will take a long time), can
    71  be done by running:
    72  
    73  ```sh
    74  cd tests && ./main.sh -A
    75  ```
    76  
    77  ### Running tests
    78  
    79  To run the tests, they can be broken down into steps:
    80  
    81  ```sh
    82  ./main.sh deploy                     # Runs deploy test suite
    83  ./main.sh deploy test_deploy_bundles # Runs test (and all of the subtests)
    84  ./main.sh deploy run_deploy_bundle   # Runs subtest
    85  ```
    86  
    87  Note: running subtests, will also invoke the parent test to ensure that it has
    88  everything setup correctly.
    89  
    90  Running `./main.sh deploy run_deploy_bundle` will also run `test_deploy_bundles`,
    91  but no other subtests, just `run_deploy_bundle`.
    92  
    93  ### Using local controllers
    94  
    95  The use of local controllers whilst development is advantagous because you don't
    96  have to rebootstrap a controller, or you can test a particular setup that has
    97  been manually created.
    98  
    99  To do so, just specify a controller name and pass it though.
   100  
   101  ```sh
   102  ./main.sh -l <local-controller-name> deploy
   103  ```
   104  
   105  Note: because you're using a local controller, you don't get the same guarantees
   106  of setup and cleanup that you can with letting the test suite do that for you.
   107  So if you expect everything to be cleaned up and leave no trace, then don't use
   108  this method of bootstrapping.