Gauge Python Release 0.1.0 Kashish Munjal May 04, 2018
Contents 1 Installation 3 1.1 Online Installation............................................ 3 1.2 Offline Installation............................................ 3 1.3 Verify installation............................................ 4 1.4 Nightly Installation............................................ 4 1.5 Verify Nightly installation........................................ 4 2 Getting Started 7 2.1 Initialization............................................... 7 2.2 Execution................................................. 7 2.3 Examples................................................. 8 3 Features 9 3.1 Step implementation........................................... 9 3.2 Execution Hooks............................................. 10 3.3 Custom messages to report........................................ 11 3.4 Data Stores................................................ 12 3.5 Refactoring................................................ 13 3.6 Debugging................................................ 13 3.7 Custom screenshot hook......................................... 13 4 Contributing 15 4.1 Issues................................................... 15 4.2 Documentation.............................................. 15 4.3 Pull Requests............................................... 15 5 FAQ 17 5.1 ImportError: No module named getgauge................................ 17 5.2 Failed to start gauge API: Plugin python not installed on following locations : [PATH]....... 17 5.3 Change/Rename default step implementation(step_impl) directory................. 17 5.4 Use different version of python while running specs.......................... 18 5.5 ImportError: No module named step_impl.<file_name>........................ 18 6 Indices and tables 19 i
ii
Author Gauge Team License MIT license Contents 1
2 Contents
CHAPTER 1 Installation Before installing gauge-python, make sure Gauge v0.3.0 or above is installed $ gauge -v Note: getgauge package supports python2.7 and python3.*. 1.1 Online Installation Run the following commands to install gauge-python $ gauge install python $ [pip / pip3] install getgauge Installing specific version $ gauge install python -v 0.2.3 $ [pip / pip3] install getgauge 1.2 Offline Installation Download the plugin from Releases_ Run the following command to install from the downloaded file $ gauge install python -f gauge-python-0.2.3.zip $ [pip / pip3] install getgauge 3
1.3 Verify installation Run the following command and plugin python should be listed in the plugin section. $ gauge -v Gauge version: 0.9.7 Plugins ------- html-report (2.1.1) python (0.2.4) To verify getgauge package is installed, run the following command and the output should contain package details. $ pip/pip3 show getgauge --- Metadata-Version: 1.1 Name: getgauge Version: 0.2.4 Summary: Enables Python support for Gauge Home-page: https://github.com/getgauge/gauge-python Author: Gauge Team Author-email: getgauge@outlook.com License: MIT Location: /usr/local/lib/python3.5/site-packages Requires: protobuf, redbaron 1.4 Nightly Installation Download the plugin from Noghtly Releases_ Run the following command to install from the downloaded file Example $ gauge install python -f gauge-python-$version.nightly.$nightly_date.zip $ [pip / pip3] install --pre getgauge==$version.dev.$nightly_date_without_ ANY_SEPARATOR $ gauge install python -f gauge-python-0.2.4.nightly.2018-02-08.zip $ [pip / pip3] install --pre getgauge==0.2.4.dev.20180208 1.5 Verify Nightly installation Run the following command and plugin python should be listed in the plugin section. 4 Chapter 1. Installation
$ gauge -v Gauge version: 0.9.8 Plugins ------- html-report (2.1.1) python (0.2.4) To verify getgauge package is installed, run the following command and the output should contain package details. $ pip/pip3 show getgauge --- Metadata-Version: 1.1 Name: getgauge Version: 0.2.4.dev.20180208 Summary: Enables Python support for Gauge Home-page: https://github.com/getgauge/gauge-python Author: Gauge Team Author-email: getgauge@outlook.com License: MIT Location: /usr/local/lib/python3.5/site-packages Requires: protobuf, redbaron 1.5. Verify Nightly installation 5
6 Chapter 1. Installation
CHAPTER 2 Getting Started If you are new to Gauge, please consult the Gauge documentation to know about how Gauge works. 2.1 Initialization To initialize a project with gauge-python, in an empty directory run: $ gauge --init python The project structure should look like this: env logs default default.properties specs example.spec step_impl step_impl.py manifest.json 2.2 Execution To execute a gauge-python project, run the following command in the project: $ gauge specs/ 7
2.3 Examples Selenium: This project serves as an example for writing automation using Gauge. It uses selenium and various Gauge/Gauge-Python features. For more details, Check out the gauge-example-python repository. Selenium and REST API: This project shows an example of how to setup Gauge, Gauge Python and Magento to test REST API. For more details, Check out the blog or gauge-magento-test repository. 8 Chapter 2. Getting Started
CHAPTER 3 Features If you are new to Gauge, please consult the Gauge documentation to know about how Gauge works. 3.1 Step implementation Use the @step(<step-text>) to implement your steps. For example: from getgauge.python import step @step("the word <word> has <number> vowels.") def hello(a, b): print("the word {} has {} vowels.".format(a, b)) 3.1.1 Multiple step names To implement the same function for multiple step names (aka, step aliases), pass an array of strings as the first argument to @step(). For example: from getgauge.python import step @step(["create a user <user name>", "Create another user <user name>"]) def hello(user_name): print("create {}.".format(user_name)) 3.1.2 Continue on failure To have a particular step implementation not break execution due to failure, use the continue_on_failure decorator. In the following example, the execution will continue if the error is an assertion error or its subclass otherwise it will halt the scenario execution. 9
from getgauge.python import step, continue_on_failure @continue_on_failure @step("create a user <user name>") def hello(user_name): assert 2 == 1 The list of errors can be provided as a parameter to continue_on_failure decorator. It will continue the execution if the error is in the given list or the subclass of any errors mentioned. For example: from getgauge.python import step, continue_on_failure @continue_on_failure([assertionerror, RuntimeError]) @step("create a user <user name>") def hello(user_name): assert 2 == 1 3.1.3 Parameters Steps can be defined to take values as parameters so that they can be re-used with different parameter values. String from getgauge.python import step @step("create another user <user name>") def hello(user_name): print("create {}.".format(user_name)) Table * Create a product Title Description Author Price -------------- -------------------- -------------- ----- Go Programming ISBN: 978-1453636671 John P. Baugh 25.00 The Way to Go ISBN: 978-1469769165 Ivo Balbaert 20.00 Go In Action ISBN: 9781617291784 Brian Ketelsen 30.00 Learning Go ebook Miek Gieben 0.00 @step('create a product <table>') def create_product(table): for row in table: PageFactory.create_page.create(row[0], row[1], row[2], row[3]) 3.2 Execution Hooks Test execution hooks can be used to run arbitrary test code as different levels during the test suite execution. For more details on hooks, refer Gauge documentation before_step 10 Chapter 3. Features
after_step before_scenario after_scenario before_spec after_spec before_suite after_suite from getgauge.python import before_step, after_scenario @before_step def before_step_hook(): print("after scenario hook") 3.2.1 Execution Context To get additional information about the current specification, scenario and step executing, an additional context parameter can be added to the hooks method. from getgauge.python import before_step, after_scenario @before_step def before_step_hook(context): print(context) 3.2.2 Tagged Execution Hooks Execution hooks can be run for specify tags. This will ensure that the hook runs only on scenarios and specifications that have the required tags. The following after_scenario hook will be run if the scenario has hello and hi. @after_scenario("<hello> and <hi>") def after_scenario_hook(): print("after scenario hook with tag") Complex tags expression can alse be used like: <hello> and <hi> or not <hey>. Note: Tagged execution hooks are not supported for before_suite and after_suite hooks. 3.3 Custom messages to report Messages.write_message(<string>): Use the Messages.write_message(<String>) function to send custom messages to gauge in your step implementations. This method takes only one string as an argument. You can call it multiple times to send multiple messages within the same step. Example: 3.3. Custom messages to report 11
from getgauge.python import Messages Messages.write_message("After scenario") 3.4 Data Stores Step implementations can share custom data across scenarios, specifications and suites using data stores. There are 3 different types of data stores based on the lifecycle of when it gets cleared. 3.4.1 Scenario store This data store keeps values added to it in the lifecycle of the scenario execution. Values are cleared after every scenario executes. Store a value: from getgauge.python import DataStoreFactory DataStoreFactory.scenario_data_store().put(key, value) Retrieve a value: DataStoreFactory.scenario_data_store().get(key) 3.4.2 Specification store This data store keeps values added to it in the lifecycle of the specification execution. Values are cleared after every specification executes. Store a value: from getgauge.python import DataStoreFactory DataStoreFactory.spec_data_store().put(key, value) Retrieve a value: DataStoreFactory.spec_data_store().get(key) 3.4.3 Suite store This data store keeps values added to it in the lifecycle of the entire suite s execution. Values are cleared after entire suite executes. Store a value: from getgauge.python import DataStoreFactory DataStoreFactory.suite_data_store().put(key, value); Retrieve a value: DataStoreFactory.suite_data_store().get(key); 12 Chapter 3. Features
Note: Suite Store is not advised to be used when executing specs in parallel. The values are not retained between parallel streams of execution. 3.5 Refactoring gauge-python supports refactoring your specifications and step implementations. Refactoring can be done using the following command signature: $ gauge --refactor "Existing step text" "New step text" The python runner plugin will alter the step text in the step decorator and function signature. 3.6 Debugging Gauge-Python supports debugging your test implementation code using pbd. import pdb The typical usage to break into the debugger from a running program is to insert pdb.set_trace() Execution will stop where it finds the above statement and you can debug. 3.7 Custom screenshot hook You can specify a custom function to grab a screenshot on step failure. By default, gauge-python takes screenshot of the current screen using the gauge_screenshot binary. Use screenshot decorator on the custom screenshot function and it should return a base64 encoded string of the image data that gauge-python will use as image content on failure. from getgauge.python import screenshot @screenshot def take_screenshot(): return "base64encodedstring" 3.5. Refactoring 13
14 Chapter 3. Features
CHAPTER 4 Contributing 4.1 Issues If you find any issues or have any feature requests, please file them in the issue tracker. If you are filing issues, please provide the version of gauge core, python, gauge-python plugin and getgauge package that you have installed. You can find it by running following commands $ gauge -v $ python --version $ pip show getgauge 4.2 Documentation You can enhance the documentation. The code for documentation is present on Github. It uses Sphinx and it is written in restructuredtext. It s free and simple. Read the Getting Started guide to get going! 4.3 Pull Requests Contributions to Gauge-Python are welcome and appreciated. Implement features, fix bugs and send us pull requests. 4.3.1 Development Guide Requirements Python Pip 15
Gauge Installing package dependencies pip install -r requirements.txt Tests python build.py --test Tests Coverage python build.py --test coverage report -m Installing python build.py --install Creating distributable python build.py --dist This will create a.zip file in bin directory and a.tar.gz file in dist directory. The zip file can be uploaded to Github release and the.tar.gz file can be uploaded to PyPi Uploading to PyPI twine upload dist/file_name Creating Nightly distributable NIGHTLY=true python build.py --dist This will create the.zip nightly file and a.dev.date.tar.gz(pypi pre release package) file. 16 Chapter 4. Contributing
CHAPTER 5 FAQ 5.1 ImportError: No module named getgauge Installing the getgauge package using pip should fix this. You can install the package by running the following command [sudo] pip install getgauge 5.2 Failed to start gauge API: Plugin python not installed on following locations : [PATH] Installing the gauge-python plugin should fix this. You can install the plugin by running the following command gauge --install python Make sure you have the getgauge package. If you don t have, run the following command to install [sudo] pip install getgauge For more details, refer Installation docs. 5.3 Change/Rename default step implementation(step_impl) directory Create python.properties file in the <PROJECT_DIR>/env/default directory and add the following line to it. 17
STEP_IMPL_DIR = PATH_TO_STEP_IMPLEMENTATION_DIR Note: The path specified in STEP_IMPL_DIR property should be relative to project root. 5.4 Use different version of python while running specs By default the language runner uses python command to run specs. To change the default behaviour, add GAUGE_PYTHON_COMMAND property to the python.properties file in the <PROJECT_DIR>/env/ default directory. GAUGE_PYTHON_COMMAND = <python_command> GAUGE_PYTHON_COMMAND = python3 GAUGE_PYTHON_COMMAND = python2 5.5 ImportError: No module named step_impl.<file_name> This error happens on older versions of Python(2.7, 3.2). Create step_impl/ init.py to fix this. 18 Chapter 5. FAQ
CHAPTER 6 Indices and tables genindex modindex search 19