diff --git a/README.rst b/README.rst index 1a491b71e..8d0e47470 100644 --- a/README.rst +++ b/README.rst @@ -11,34 +11,8 @@ Airgun Airgun is a Python library which is build over `Widgetastic`_ and `navmazing`_ to make Satellite 6 UI testing easier. -Quick start guide ------------------ - -1. Clone robottelo branch which supports airgun: - -.. code-block:: bash - - git clone -b airgun_poc --single-branch https://github.com/abalakh/robottelo.git - -2. Install requirements - -.. code-block:: bash - - cd robottelo && pip install -r requirements.txt - -3. Create robottelo.properties file and fill it with your values (your may -reuse already existing properties file since no changes were introduced there) - -.. code-block:: bash - - cp robottelo.properties.sample robottelo.properties - vim robottelo.properties - -4. Run airgun tests from robottelo's ``tests/foreman/ui_airgun/`` folder - -.. code-block:: bash - - pytest tests/foreman/ui_airgun/test_architecture.py +For more info please see `documentation`_. .. _Widgetastic: https://github.com/RedHatQE/widgetastic.core .. _navmazing: https://github.com/RedhatQE/navmazing/ +.. _documentation: https://airgun.readthedocs.io/ diff --git a/docs/build-docs.rst b/docs/build-docs.rst index 1af312aa3..da38e4c87 100644 --- a/docs/build-docs.rst +++ b/docs/build-docs.rst @@ -7,3 +7,10 @@ To build documentation locally, use: pip install -r requirements-optional.txt make docs-html + +You might also try to run spell check: + +.. code-block:: bash + + pip install -r requirements-optional.txt + make docs-spelling diff --git a/docs/index.rst b/docs/index.rst index daf0cb511..4ec0cfad6 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -4,6 +4,10 @@ AirGun AirGun is a Python library which is build over `Widgetastic`_ and `navmazing`_ to make Satellite 6 UI testing easier. +AirGun is written in Python 3 and do not plan to support Python 2. AirGun +supports Satellite 6.4 and above and Foreman 1.17 and above (with vertical +navigation). + This page provides a summary of information about AirGun. .. contents:: @@ -17,6 +21,40 @@ More in-depth coverage is provided in other sections. api/index examples + +Concepts +-------- + +Besides code which implements Widgetastic and navmazing functionality, two +basic concepts used to abstract Satellite/Foreman UI functionality are Views +and Entities. + +**View** is fundamental basic concept that describes appearance of the page. +Here we store all information about controls (widgets) on the page, +specifically locators to them or when control is basic one that has common +locator we just define widget without any further details. Of course, we +try to address locators using `id=` or `name=` as first priority, but if we +can't - we go with XPath. If you see situation like this - create Foreman or +Katello pull request to assign unique id attribute for necessary element +where it is reasonable, as XPaths are more fragile and has worse performance +to interact with. + +**Entity** is fundamental basic concept that is responsible for functional +side of application (Satellite in our case). It defines actions you can do +with objects like CRUD (create, remove, update, delete) for example. That +is only API that is visible for end user on test side. Also, we put all +details about navigation here, so framework knows how to get to necessary +page when you need to create specific object in the application. + +AirGun adds bunch of **widgets** (which are specific to Satellite / Foreman +web UI) to these defined by Widgetastic (like generic `Text`). Widgets allows +you to interact with various UI elements and are used in views. + +And finally tests. Tests are not part of AirGun repository. You can +contribute tests to the Robottelo (currently only in abalakh's fork, `branch +airgun_poc`_ (see "Quick start guide" below). + + Quick start guide ----------------- @@ -46,5 +84,47 @@ reuse already existing properties file since no changes were introduced there) pytest tests/foreman/ui_airgun/test_architecture.py + +Contributing +------------ + +Good practice when working with Python project as AirGun is to work in +Python's virtual environments. To initiate and activate them before running +`pip ...` commands run: + +.. code-block:: bash + + virtualenv venv # on Fedora you might need to use `virtualenv-3` if you have Python 2 as a default on your system + source venv/bin/activate + +If you are about to start contributing, please follow `GitHub flow`_. + +For a new-comer, we have issues tagged with "`good first issue`_" so that +might be place where you can start? + +When testing your AirGun code using Robottelo tests, you can make sure your +development checkout of Airgun is used (instead the one installed in your +Robottelo virtual environment) by setting `PYTHONPATH` properly (you can +add that line at the end of your virtual environment activation script +`venv/bin/activate` so it is set automatically next time you source it): + +.. code-block:: bash + + export PYTHONPATH="/home/pok/Checkouts/airgun/airgun/:$PYTHONPATH" + +When you are running your tests locally, you will need Chrome browser +installed and `chromedriver`_ (download and unzip it) binary location +set in `webdriver_binary=` configuration option in your +`robottelo.properties` (or make it available somewhere in your PATH, +e.g. in Robottelo `venv/bin/`). + +As of now, `only chromedriver`_ is supported. + + .. _Widgetastic: https://github.com/RedHatQE/widgetastic.core .. _navmazing: https://github.com/RedhatQE/navmazing/ +.. _branch airgun_poc: https://github.com/abalakh/robottelo/tree/airgun_poc/tests/foreman/ui_airgun +.. _GitHub flow: https://help.github.com/articles/github-flow/ +.. _good first issue: https://github.com/SatelliteQE/airgun/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22 +.. _chromedriver: https://sites.google.com/a/chromium.org/chromedriver/downloads +.. _only chromedriver: https://github.com/SatelliteQE/airgun/issues/1 diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt index 5082bd1e3..2171a1e9b 100644 --- a/docs/spelling_wordlist.txt +++ b/docs/spelling_wordlist.txt @@ -1,18 +1,26 @@ +abalakh AirGun -Robottelo -saucelabs +boolean +cetera +checkbox +checkboxes +et +init +javascript jQuery +Katello +lifecycle +locator +multiselect Patternfly prequisite -webdriver -init +robottelo +Robottelo +saucelabs +screenshot +Subnet url -widgetastic -et -cetera -boolean versa -multiselect -checkboxes -screenshot -locator +webdriver +widgetastic +XPaths