diff --git a/docs/quick-start.md b/docs/quick-start.md index 7737221e7..942763d27 100644 --- a/docs/quick-start.md +++ b/docs/quick-start.md @@ -1,241 +1,41 @@ # Quick start guide - -## Before reading - -This is work in progress and what documented here is still under development. -Some of below sections should be shorter here and more detailed in dedicated -documents. Because this documentation is a Draft for features still to be -implemented and discussed, its format and organization is secondary at this -stage and it is probably going to change soon. - -## Overview - -Tobiko is a tool used to prepare cloud test resources for system testing and -make them accessible to test cases written in Python with (or without) tempest. -The main purpose of Tobiko is taking out test resources management from test -cases to allow them to have a longer life than test case execution. - -This a fundamental requirement that motivated this project with the purpose of -testing global cloud operations like whole cloud upgrades, reboot, migration. -It could also be used to test other smaller scale operations like for -example single node evacuation. - -To avoid re-inventing the wheel Tobiko integrates some pre-existing tools -with the purpose of setting up and managing test resources. Example of such -tools integrated or to be integrated are: - - - OpenStack Python clients - - - OpenStack Heat Orchestration Service to manage test resources. The test - developer is expected to use Heat as core tool for writing part of its test - cases, in special cases test fixtures to reach initial test case state - and to prepare test resources to be used inside test case. Tobiko should - provide a Python interface to create Heat stacks starting from user provided - "Heat Orchestartion Templates" and configuration parameters taken from - user provided tobiko.conf file. - - - (TODO) Ansible Configuration Management tool user to prepare testing - environment and test fixtures. Some fixtures are better handled by this - non-Openstack generic tool, even if it offers a completely different approach - to achieve the same purpose of Heat. Test developer should decide when to - prefer this tool or others according his experience and his goals. - -This is another peculiar aspect of Tobiko that distinguish it from other tools -like Tempest and it is being chosen mostly to take advantage of a good mature -production tool-set before introducing a new one from scratch. - -It has been discussed about using tempest as fundamental toolset for setting -up resources and it has been forecast that to avoid some limitations and -complications Tempest has, it would be better to choose Orchestration -tools that has specifically designed for managing cloud resources from its -fundamentals. This has also another implicit minor advantage: Tobiko is also -a tool for testing Heat and regular OpenStack Python clients, while tempest -choose to re-implement clients and resources management from scratch (work -mostly incomplete and under very slow maintenance). - - ## Install Tobiko -Tobiko is preferably used from a dedicated virtual environment: - -``` -virtualenv path/to/virtualenv -source path/to/virtualenv/bin/activate -``` - -You can download Tobiko source code and install it in a single step inside -your environment by typing: - -``` -pip install git+https://git.openstack.org/openstack/tobiko -``` - -or simply - -``` +virtualenv path/to/yuor/venv +source path/to/yuor/venv/bin/activate pip install tobiko -``` -Tobiko doesn't need to be used from its source code directory, so, by instance, -after you installed it, you could use it as any Python tool from the directory -where your own test files are. +## Set up credentials -Tobiko is also distributed together with some example test cases that could -be used as a reference and this option grants you the ability to see if Tobiko -is properly installed on your system. +In order to run the tests successfully you'll need to set up OpenStack credentials. +You can do it in one of two ways: + +1. Using environment variables. + Either by downloading the credentials file directly from your OpenStack project or + setting them up manually like this: + + export API_VERSION = 2 + export OS_USERNAME = admin + export OS_PASSWORD = admin + export PROJECT_NAME = admin + export OS_USER_DOMAIN_NAME="Default" + export OS_PROJECT_DOMAIN_NAME = admin + export OS_AUTH_URL=https://my_cloud:13000/v3 -## Tobiko Workflow +2. Setting up tobiko.conf file with the following format: -Here we are going to describe the typical Tobiko workflow in a few simple -steps + api_version = 2 + username = admin + password = admin + project_name = admin + user_domain_name = admin + project_domain_name = admin + auth_url = http://my_cloud:13000/v3 +## Run Tests -### Step 1) Set up your cloud +To run neutron tests, use the following command: -Tobiko requires a pre-installed OpenStack cloud. As it relies on -python-openstackclient, you also have to assign environment variable with -the client credentials. - -``` -source -``` - -for example: - -``` -source overcloudrc -``` - -In order to verify Tobiko's connectivity, exectute following command: - -``` -openstack stack list -``` - -#### Configure Tobiko - -Create your tobiko.conf file - -TODO: document here minimal configuration file options required for executing -test cases. - - -### Step 2) Populate test resources - -Tobiko creates a set of persisting resources (eventually using Heat) to be used -in test cases. - -``` -tobiko create -``` - -Tobiko is going to look into the current folder, searching into all registered -Python test packages for all test modules (Python files matching wildcard -expression ```test_*.py```). Every test case would eventually have a reference -to some Tobiko fixture. Some of these fixtures could be used as an example of a -stack of resources orchestracted from OpenStack Heat tool. By importing those -test case modules Tobiko will be able to find these fixtures and set them all -up. - -The list of these fixtures can be narrowed down by using expressions to select -test cases to be considered. A test case could also be identified from its Python -source code files as below: - -``` -tobiko create [-f|--file] ... -``` - -Or it could be restricted using test case packages or file names as below: - -``` -tobiko create (-m|--module) ... -``` - -To have a summary of all test cases which resources could be set up using -Tobiko you could type: - -``` -tobiko list -``` - -To have a summary of all test cases which resources has been actually set up -using Tobiko you can type: - -``` -tobiko list (-e|--existing) -``` - - -### 3) Run test cases - -Once test cloud resources (also called here Tobiko test fixtures) are ready to -be used, test cases can finally be executed to check if the cloud is working by -executing test cases with such preconfigured test resources. - -To run test cases you can type: - -``` -tobiko run ... -``` - -or similarly to Tobiko create command: - -``` -tobiko run [-m|--module] ... -``` - -You can also use your favorite Python test runner as there are very good ones -around. - -``` -stestr ... -``` - -Please note Tobiko is only a wrapper around your favorite test runner and -you could change it by configuring Tobiko. - -The first time that a test case requires test resources managed by Tobiko then -Tobiko is going to discover test case resources from your given stack name. -To achieve it, test case developer is expected to use Tobiko Python API. - - -### 4) Execute your cloud operation - -In this step you should execute a sequence of cloud operations that you want to -test. For example you could upgrade your OpenStack installation in order to see -if the test resources managed by Tobiko are still working as expected. - - -### 5) Run test cases again - -After executing your operations on top of your OpenStack instance, you should -expect test resources set up by Tobiko to still be there and they should pass -the same test cases that has been passed at step 3. So here you should execute -the same command line you executed at step 3: - -``` -tobiko run [] -``` - - -### 6) Cleanup all populated resources - -Finally once all your tests has been executed you can ask Tobiko to cleanup -all resources by typing below command: - -``` -tobiko delete -``` - -The previous command could also be more selective by deleting only test resources -for specific test cases: - -``` -tobiko delete -``` - -``` -tobiko delete (-m|--module) -``` + tox -e neutron