|
| 1 | +# Juju Functional Tests |
| 2 | + |
| 3 | +## Running Test Scripts |
| 4 | + |
| 5 | +Some setup is required before running the tests. |
| 6 | + |
| 7 | +### Installing dependencies |
| 8 | + |
| 9 | +Dependencies are installed via a .deb and pip install. |
| 10 | + |
| 11 | +```bash |
| 12 | +$ sudo apt-get install make |
| 13 | + |
| 14 | +$ make install-deps |
| 15 | +``` |
| 16 | + |
| 17 | +### Required Environment Variables |
| 18 | + |
| 19 | + * **JUJU_HOME**: The directory the test will use to: |
| 20 | + * Find environments.yaml [(see use of environments.yaml below)](#envs) |
| 21 | + * Find credentials.yaml [(see use of credentials.yaml below)](#envs-creds) |
| 22 | + * Create a **JUJU_DATA** dir for use for the duration of the test. The directory is created in: $JUJU_HOME/juju-homes/. |
| 23 | + * **JUJU_REPOSITORY**: The directory containing the local dummy charms. You can use '\<juju root\>/acceptancetests/repository'. |
| 24 | + |
| 25 | + |
| 26 | +### Quick run using LXD |
| 27 | +To run a test locally with lxd: |
| 28 | + |
| 29 | + * ```$ mkdir /tmp/test-run``` |
| 30 | + * ```$ export JUJU_HOME=/tmp/test-run``` |
| 31 | + * ```$ vim $JUJU_HOME/environments.yaml``` |
| 32 | + ```yaml |
| 33 | + environments: |
| 34 | + lxd: |
| 35 | + type: lxd |
| 36 | + test-mode: true |
| 37 | + default-series: xenial |
| 38 | + ``` |
| 39 | + * ```export JUJU_REPOSITORY=./path/to/acceptancetests/repository``` |
| 40 | + * Now you can run the test with: |
| 41 | + * ```$ ./assess_model_migration.py lxd . . .``` |
| 42 | + |
| 43 | +### Quick run using AWS |
| 44 | + |
| 45 | +See [(Use of environments.yaml below)](#envs) and [(Use of credentials.yaml below)](#envs-creds) for a full explanation of the files used here. |
| 46 | + |
| 47 | +To run a test using AWS: |
| 48 | + |
| 49 | + * ```$ mkdir /tmp/test-run``` |
| 50 | + * ```$ export JUJU_HOME=/tmp/test-run``` |
| 51 | + * ```$ vim $JUJU_HOME/environments.yaml``` |
| 52 | + ```yaml |
| 53 | + environments: |
| 54 | + myaws: |
| 55 | + type: ec2 |
| 56 | + test-mode: true |
| 57 | + default-series: xenial |
| 58 | + region: us-east-1 |
| 59 | + ``` |
| 60 | + * ```$ vim $JUJU_HOME/credentials.yaml``` |
| 61 | + ```yaml |
| 62 | + credentials: |
| 63 | + aws: |
| 64 | + credentials: |
| 65 | + auth-type: access-key |
| 66 | + access-key: <access key> |
| 67 | + secret-key: <secret key> |
| 68 | + ``` |
| 69 | + * ```export JUJU_REPOSITORY=/path/to/acceptancetests/repository``` |
| 70 | + * Now you can run the test with: |
| 71 | + * ```$ ./assess_model_migration.py myaws . . .``` |
| 72 | + |
| 73 | +### Which juju binary is used? |
| 74 | + |
| 75 | +If no *juju_bin* argument is passed to an *assess* script it will default to using the juju in your **$PATH**. |
| 76 | + |
| 77 | +So, to use a locally build juju binary either: |
| 78 | + |
| 79 | + * Ensure you binary is in **$PATH** (i.e. export PATH=/home/user/src/Go/bin:$PATH) |
| 80 | + * Or explicitly pass it to the *assess* script: ./assess_something.py lxd /home/user/src/Go/bin/juju |
| 81 | + |
| 82 | +### Using an existing controller |
| 83 | + |
| 84 | +Some tests have the ability to be run against an already bootstrapped controller (saving the need for the test to do the bootstrapping). |
| 85 | +This feature is available via the ```--existing``` argument for an *assess* script. Check the ```--help``` output to see if the *assess* script you want to run supports this. |
| 86 | + |
| 87 | +Adding this feature to a new test is as easy as passing ```existing=True``` to ```add_basic_testing_arguments``` which will enable the argument in the script. |
| 88 | + |
| 89 | +### Running a test on an existing controller |
| 90 | + |
| 91 | +To iterate quickly on a test it can be useful to bootstrap a controller and run the test against that multiple times. |
| 92 | +This example isolates the juju interactions so your system configuration is not touched. |
| 93 | + |
| 94 | +```bash |
| 95 | +# Use freshly built juju binaries |
| 96 | +export PATH=/home/user/src/Go/bin:$PATH |
| 97 | +export JUJU_DATA=/tmp/testing-controller |
| 98 | +# The test will still need JUJU_HOME to find it's environment.yaml and credentials.yaml |
| 99 | +export JUJU_HOME=~/cloud-city/ |
| 100 | +mkdir -p $JUJU_DATA |
| 101 | +
|
| 102 | +juju bootstrap lxd/localhost testing-feature-x |
| 103 | +
|
| 104 | +./assess_feature-x.py lxd --existing testing-feature-x |
| 105 | +``` |
| 106 | + |
| 107 | +**Note:** If you don't explicitly set **JUJU_DATA** the test will check for an existing path in this order: |
| 108 | + |
| 109 | + 1. **$JUJU_DATA** |
| 110 | + 1. **$XDG_DATA_HOME**/juju |
| 111 | + 1. **$HOME**/.local/share/juju |
| 112 | + |
| 113 | +### Keeping an environment after a run |
| 114 | + |
| 115 | +Normally a test script will teardown any bootstrapped controllers, if you wish to investigate the environment after a run use ```--keep-env``. |
| 116 | +Using the ```--keep-env``` option will skip any teardown of an environment at the end of a test. |
| 117 | + |
| 118 | +### Use of environments.yaml<a name="envs"></a> |
| 119 | + |
| 120 | +Jujupy test framework uses the *environments.yaml* file found in **JUJU_HOME** to define configuration for a bootstrap-able environment. |
| 121 | +The file follows the Juju1 schema for the file of the same name. |
| 122 | + |
| 123 | +The **env** argument to an assess script is a mapping to an environment defined in this file. |
| 124 | + |
| 125 | +For instance if you defined an environment named testing123 of type LXD: |
| 126 | + |
| 127 | +```yaml |
| 128 | +environments: |
| 129 | + testing123: |
| 130 | + type: lxd |
| 131 | + test-mode: true |
| 132 | + default-series: xenial |
| 133 | + # You can use config like this too: |
| 134 | + # agent-metadata-url: https://custom.streams.bucket.com |
| 135 | +``` |
| 136 | + |
| 137 | +You can pass that to an assess script: |
| 138 | + |
| 139 | +```./assess_model_migration.py testing123``` |
| 140 | + |
| 141 | +And it will bootstrap using LXD (and won't need a credentials.yaml file, as it's not needed with LXD). |
| 142 | + |
| 143 | +### Use of credentials.yaml<a name="envs-creds"></a> |
| 144 | + |
| 145 | +The Jujupy test framework can use a credentials.yaml file (it looks in $JUJU_HOME) to provide credentials for providers that need it. |
| 146 | + |
| 147 | +The format of the file follows that of Juju1 credentials.yaml, an example: |
| 148 | + |
| 149 | +```yaml |
| 150 | +credentials: |
| 151 | + aws: |
| 152 | + credentials: |
| 153 | + auth-type: access-key |
| 154 | + access-key: abc123 |
| 155 | + secret-key: abc123 |
| 156 | +``` |
| 157 | + |
1 | 158 | # Creating a New CI Test |
2 | 159 |
|
3 | 160 | Test scripts will be run under many conditions to reproduce real cases. |
|
0 commit comments