Gauge API Steps

A Python module, that provides re-usable steps for testing APIs with the Gauge framework.

Description

This is an extensible and flexible test-automation library for Gauge. It enables users with and without programming knowledge to create end-to-end test scenarios in Markdown syntax. Developers can still easily extend their test scenarios with custom code. Python's urllib is used to make requests against APIs. XML and JSON are supported and API responses can be validated with XPath and JSONPath.

Gauge Step Overview

Find the documentation on all Gauge steps of this project in the overview:

Gauge Step Overview

Quick Start

This is a library for the Gauge framework, so Gauge+Python must be installed first.

• Install Python >= 3.13 on your platform and make it available in the $PATH
• Install Gauge and create a test project with Python

It is useful to understand the basic workings of Gauge first. The documentation is excellent.

• Install the gauge-api-steps module
• Find out the path to this module after installation:
  It should be in <project>/virtualenvironment/lib/python/site-packages/gauge_api_steps
• Add that path to the property STEP_IMPL_DIR inside the test project file env/default/python.properties. Paths to multiple modules are comma separated.
  Example on a Mac:

  STEP_IMPL_DIR = /<gauge-project-path>/virtualenvironment/lib/python/site-packages/gauge_api_steps, step_impl
  

• Restart Visual Studio Code
• Write a new scenario in specs/example.spec. VSC offers auto-completion

Installation

First, create a virtual environment in your Gauge project directory.

cd <project>
python -m venv virtualenvironment
source virtualenvironment/bin/activate

The Gauge module loader does not like dots . in directories, so a link must be created in the virtual environment for the python packages:

cd <project>/virtualenvironment
ln -sf python3.13 python

Afterwards, the latest version can be downloaded and installed from PyPi:

pip install gauge-api-steps --upgrade

Alternatively, it can also be installed from source:

cd path/to/gauge-api-steps
pip install .

Development

When coding on this project, unit tests can be executed like this:

python -m unittest discover -v -s tests/ -p 'test_*.py'

Contributions are welcome.

Configuration

The Configuration follows the Gauge configuration approach. A lot of behaviour, including redirect rules, logging, and secret masking, can be determined with properties.

Configuration Overview

Expressions in Parameters

Property Placeholders

Step parameters allow the use of placeholders, that can be defined in the Gauge environment properties files. Some steps also allow to set a placeholder value manually. Property keys act as placeholders, they are defined like ${key}. They will be replaced by its value if such a property key/value pair exists in any env/*/*.properties file or within the execution scope.

Mathematical Expressions

Mathematical expressions can also be evaluated. For example: #{5 + 5 * 5} is evaluated to 30.

It is possible to combine the two features. Placeholder substitution takes place before mathematical expression evaluation.

Functional Expressions

Functional expressions will generate a result during step execution. There are different expressions:

• UUID generation: !{uuid}
• Time: !{time}, !{time:%Y-%m-%d} - The time format is optional. If omitted, ISO format will be used. The time format pattern is described in the Python language documentation.
• Encode Base64: !{base64:${user}:${password}} - Encodes the given value into Base64.
• Encode Base64 in URL-safe mode: !{base64urlsafe:${value}} - Encodes the given value into Base64 with + and / replaced by - and _.
• Decode Base64: !{base64decode:dXNlcjpwYXNz} - Decodes Base64 back to a string. It can handle standard and URL-safe variants and accepts input without padding.
• URL-Encode: !{urlencode:?param one/two?} - URL-encodes the given value. Spaces will be replaced with +.
• URL-Decode: !{urldecode:%3Fparam%20one%2Ftwo%3F} - URL-decodes the given value. +-signs will be replaced with spaces.
• Load content from text file: !{file:resources/file.json} - The File must be inside the project directory.
• Load graphQL from files: !{gql:resources/query.gql} or !{graphql:resources/query.gql} - This will automatically generate the JSON format, that can be used in the request body.
  • Variables and operation name is also supported. Values are colon-separated like so: !{gql:resources/query.gql:resources/vars.gql:my-operation}

Expression Examples

Note that the property expressions start with $, mathematical expressions with #, and functional expressions with !.

The property "homepage_url" can be defined in env/default/test.properties like this:

homepage_url = https://my-app.net

* Request "GET" "${homepage_url}/home"

* Print "5 + 6 = #{5 + 6}"

It is also possible to define a property in a step:

* Store "addend" "5"

* Print "5 + 5 * 5 = #{$addend + 5 * 5}"

And also to create new properties from old:

* Store "new_url" "${base_url}/id=!{uuid}&created=!{time}"

* Print "!{uuid}"

* Print "!{time}"

* Print "!{time:%Y-%m-%d}"

* Print "!{base64:user:password}"

* Print "!{base64urlsafe:param one}"

* Print "!{base64decode:dXNlcjpwYXNz}"

* Print "!{urlencode:?param one/two?}"

* Print "!{urldecode:%3Fparam%20one%2Ftwo%3F}"

* With body "!{file:resources/request.json}"

* With body "!{file:resources/request.xml}"

* With body "!{gql:resources/request.gql}"

* With body "!{gql:resources/request.gql:resources/variables.gql}"

* With body "!{gql:resources/request.gql:resources/variables.gql:operation-name}"

Internal Placeholders

Following placeholders are used internally to store data over multiple steps:

• _opener
• _response_csrf_header
• _request_csrf_header
• _csrf_value
• _body
• _response
• _headers

It is possible to access and manipulate them with certain steps.

Maintainers

Maintainers