1# Gophercloud Acceptance tests
2
3The purpose of these acceptance tests is to validate that SDK features meet
4the requirements of a contract - to consumers, other parts of the library, and
5to a remote API.
6
7> **Note:** Because every test will be run against a real API endpoint, you
8> may incur bandwidth and service charges for all the resource usage. These
9> tests *should* remove their remote products automatically. However, there may
10> be certain cases where this does not happen; always double-check to make sure
11> you have no stragglers left behind.
12
13### Step 1. Creating a Testing Environment
14
15Running tests on an existing OpenStack cloud can be risky. Malformed tests,
16especially ones which require Admin privileges, can cause damage to the
17environment. Additionally, you may incur bandwidth and service charges for
18the resources used, as mentioned in the note above.
19
20Therefore, it is usually best to first practice running acceptance tests in
21an isolated test environment. Two options to easily create a testing
22environment are [DevStack](https://docs.openstack.org/devstack/latest/)
23and [PackStack](https://www.rdoproject.org/install/packstack/).
24
25The following blog posts detail how to create reusable PackStack environments.
26These posts were written with Gophercloud in mind:
27
28* http://terrarum.net/blog/building-openstack-environments.html
29* http://terrarum.net/blog/building-openstack-environments-2.html
30* http://terrarum.net/blog/building-openstack-environments-3.html
31
32### Step 2. Set environment variables
33
34A lot of tests rely on environment variables for configuration - so you will need
35to set them before running the suite. If you're testing against pure OpenStack APIs,
36you can download a file that contains all of these variables for you: just visit
37the `project/access_and_security` page in your control panel and click the "Download
38OpenStack RC File" button at the top right. For all other providers, you will need
39to set them manually.
40
41#### Authentication
42
43|Name|Description|
44|---|---|
45|`OS_USERNAME`|Your API username|
46|`OS_PASSWORD`|Your API password|
47|`OS_AUTH_URL`|The identity URL you need to authenticate|
48|`OS_TENANT_NAME`|Your API tenant name|
49|`OS_TENANT_ID`|Your API tenant ID|
50
51#### General
52
53|Name|Description|
54|---|---|
55|`OS_REGION_NAME`|The region you want your resources to reside in|
56
57#### Compute
58
59|Name|Description|
60|---|---|
61|`OS_IMAGE_ID`|The ID of the image your want your server to be based on|
62|`OS_FLAVOR_ID`|The ID of the flavor you want your server to be based on|
63|`OS_FLAVOR_ID_RESIZE`|The ID of the flavor you want your server to be resized to|
64|`OS_POOL_NAME`|The Pool from where to obtain Floating IPs|
65|`OS_NETWORK_NAME`|The internal/private network to launch instances on|
66|`OS_EXTGW_ID`|The external/public network|
67
68#### Database
69
70|Name|Description|
71|---|---|
72|`OS_DB_DATASTORE_TYPE`|The Datastore type to use. Example: `mariadb`|
73|`OS_DB_DATASTORE_VERSION`|The Datastore version to use. Example: `mariadb-10`|
74
75#### Shared file systems
76|Name|Description|
77|---|---|
78|`OS_NETWORK_ID`| The network ID to use when creating shared network|
79|`OS_SUBNET_ID`| The subnet ID to use when creating shared network|
80
81### 3. Run the test suite
82
83From the root directory, run:
84
85```
86./script/acceptancetest
87```
88
89Alternatively, add the following to your `.bashrc`:
90
91```bash
92gophercloudtest() {
93  if [[ -n $1 ]] && [[ -n $2 ]]; then
94    pushd  $GOPATH/src/github.com/gophercloud/gophercloud
95    go test -v -tags "fixtures acceptance" -run "$1" github.com/gophercloud/gophercloud/acceptance/openstack/$2 | tee ~/gophercloud.log
96    popd
97fi
98}
99```
100
101Then run either groups or individual tests by doing:
102
103```shell
104$ gophercloudtest TestFlavorsList compute/v2
105$ gophercloudtest TestFlavors compute/v2
106$ gophercloudtest Test compute/v2
107```
108
109### 4. Notes
110
111#### Compute Tests
112
113* In order to run the `TestBootFromVolumeMultiEphemeral` test, a flavor with ephemeral disk space must be used.
114* The `TestDefSecRules` tests require a compatible network driver and admin privileges.
115