github.com/gophercloud/gophercloud@v1.11.0/internal/acceptance/README.md (about)

     1  # Gophercloud Acceptance tests
     2  
     3  The purpose of these acceptance tests is to validate that SDK features meet
     4  the requirements of a contract - to consumers, other parts of the library, and
     5  to 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  
    15  Running tests on an existing OpenStack cloud can be risky. Malformed tests,
    16  especially ones which require Admin privileges, can cause damage to the
    17  environment. Additionally, you may incur bandwidth and service charges for
    18  the resources used, as mentioned in the note above.
    19  
    20  Therefore, it is usually best to first practice running acceptance tests in
    21  an isolated test environment. Two options to easily create a testing
    22  environment are [DevStack](https://docs.openstack.org/devstack/latest/)
    23  and [PackStack](https://www.rdoproject.org/install/packstack/).
    24  
    25  The following blog posts detail how to create reusable PackStack environments.
    26  These 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  
    34  A lot of tests rely on environment variables for configuration - so you will need
    35  to set them before running the suite. If you're testing against pure OpenStack APIs,
    36  you can download a file that contains all of these variables for you: just visit
    37  the `project/access_and_security` page in your control panel and click the "Download
    38  OpenStack RC File" button at the top right. For all other providers, you will need
    39  to 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  
    77  |Name|Description|
    78  |---|---|
    79  |`OS_NETWORK_ID`| The network ID to use when creating shared network|
    80  |`OS_SUBNET_ID`| The subnet ID to use when creating shared network|
    81  
    82  #### Container infra
    83  
    84  |Name|Description|
    85  |---|---|
    86  |`OS_MAGNUM_IMAGE_ID`| The ID of a valid magnum image|
    87  |`OS_MAGNUM_KEYPAIR`| The ID of a valid keypair|
    88  
    89  ### 3. Run the test suite
    90  
    91  From the root directory, run:
    92  
    93  ```
    94  ./script/acceptancetest
    95  ```
    96  
    97  Alternatively, add the following to your `.bashrc`:
    98  
    99  ```bash
   100  gophercloudtest() {
   101    if [[ -n $1 ]] && [[ -n $2 ]]; then
   102      pushd  $GOPATH/src/github.com/gophercloud/gophercloud
   103      go test -v -tags "fixtures acceptance" -run "$1" github.com/gophercloud/gophercloud/internal/acceptance/openstack/$2 | tee ~/gophercloud.log
   104      popd
   105  fi
   106  }
   107  ```
   108  
   109  Then run either groups or individual tests by doing:
   110  
   111  ```shell
   112  $ gophercloudtest TestFlavorsList compute/v2
   113  $ gophercloudtest TestFlavors compute/v2
   114  $ gophercloudtest Test compute/v2
   115  ```
   116  
   117  ### 4. Notes
   118  
   119  #### Compute Tests
   120  
   121  * In order to run the `TestBootFromVolumeMultiEphemeral` test, a flavor with ephemeral disk space must be used.
   122  * The `TestDefSecRules` tests require a compatible network driver and admin privileges.