# Gauge API Steps
[](./LICENCE)
[](https://www.python.org/downloads/release/python-31012/)
[](https://github.com/getgauge)
[](https://www.w3schools.com/xml/xpath_syntax.asp)
[](https://github.com/h2non/jsonpath-ng)
[](https://securityscorecards.dev/viewer/?uri=github.com/IBM/gauge-api-steps)
A Python module, that provides re-usable steps for testing APIs with the [Gauge](https://gauge.org/) framework.
## Description
This is an extensible and flexible test-automation library for [Gauge](https://gauge.org). It enables users with and without programming knowledge to create end-to-end test scenarios in [Markdown](https://www.markdownguide.org/) 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](https://github.com/IBM/gauge-api-steps/tree/master/docs/STEPS.md)
## Quick Start
This is a library for the Gauge framework, so Gauge+Python must be installed first.
* Install Python >= 3.10 on your platform and make it available in the \$PATH
* Install [Gauge](https://docs.gauge.org/getting_started/installing-gauge.html?language=python&ide=vscode) and [create a test project with Python](https://docs.gauge.org/getting_started/create-test-project.html?os=macos&language=python&ide=vscode)
It is useful to understand the basic workings of Gauge first. The [documentation](https://docs.gauge.org/?os=macos&language=python&ide=vscode) is excellent.
* Install [this module](#installation)
* Find out the path to this module after installation:
```shell
echo $( python -m site --user-site )/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 = /Users/<user>/Library/Python/3.10/lib/python/site-packages/gauge_api_steps, step_impl
```
* Reload Visual Studio Code
* Write a new scenario in `specs/example.spec`. VSC offers **auto-completion**
## Installation
This module can be installed from source:
```shell
cd path/to/gauge-api-steps
pip install --user .
```
Or the latest package can be downloaded and installed from [PyPi](https://pypi.org/project/gauge-api-steps):
```shell
pip install gauge-api-steps --user --upgrade
```
## Development
When coding on this project, unit tests can be executed like this:
```shell
python -m unittest discover -v -s tests/ -p 'test_*.py'
```
[Contributions are welcome](https://github.com/IBM/gauge-api-steps/tree/master/docs/CONTRIBUTING.md).
## 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](https://docs.python.org/3.10/library/time.html#time.strftime).
* Load content from text file: `!{file:resources/file.json}` The File must be inside the project directory.
* Load graphQL from file: `!{gql:resources/file.gql}` or `!{graphql:resources/file.gql}` This will automatically generate the JSON format, that can be used in the request body.
### 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}"
> \* With body "!{file:resources/request.json}"
> \* With body "!{file:resources/request.xml}"
> \* With body "!{gql:resources/request.gql}"
### 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.
## Configuration
The Configuration follows the [Gauge configuration](https://docs.gauge.org/configuration.html?os=linux&language=python&ide=vscode) approach.
Some behaviour can be determined with properties.
[Configuration Overview](https://github.com/IBM/gauge-api-steps/tree/master/docs/CONFIG.md)
## Maintainers
[Maintainers](https://github.com/IBM/gauge-api-steps/tree/master/docs/MAINTAINERS.md)
Raw data
{
"_id": null,
"home_page": "https://github.com/IBM/gauge-api-steps",
"name": "gauge-api-steps",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Tobias Lehmann",
"author_email": "derdualist1@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/d3/31/dfa2b9f49db7276f917d6d089bdda074d9202b8f835e339c6c21e54e7772/gauge-api-steps-0.20.tar.gz",
"platform": null,
"description": "# Gauge API Steps\n\n[](./LICENCE)\n[](https://www.python.org/downloads/release/python-31012/)\n[](https://github.com/getgauge)\n[](https://www.w3schools.com/xml/xpath_syntax.asp)\n[](https://github.com/h2non/jsonpath-ng)\n[](https://securityscorecards.dev/viewer/?uri=github.com/IBM/gauge-api-steps)\n\nA Python module, that provides re-usable steps for testing APIs with the [Gauge](https://gauge.org/) framework.\n\n## Description\n\nThis is an extensible and flexible test-automation library for [Gauge](https://gauge.org). It enables users with and without programming knowledge to create end-to-end test scenarios in [Markdown](https://www.markdownguide.org/) 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.\n\n## Gauge Step Overview\n\nFind the documentation on all Gauge steps of this project in the overview:\n\n[Gauge Step Overview](https://github.com/IBM/gauge-api-steps/tree/master/docs/STEPS.md)\n\n## Quick Start\n\nThis is a library for the Gauge framework, so Gauge+Python must be installed first.\n\n* Install Python >= 3.10 on your platform and make it available in the \\$PATH\n* Install [Gauge](https://docs.gauge.org/getting_started/installing-gauge.html?language=python&ide=vscode) and [create a test project with Python](https://docs.gauge.org/getting_started/create-test-project.html?os=macos&language=python&ide=vscode)\n\nIt is useful to understand the basic workings of Gauge first. The [documentation](https://docs.gauge.org/?os=macos&language=python&ide=vscode) is excellent.\n\n* Install [this module](#installation)\n* Find out the path to this module after installation:\n ```shell\n echo $( python -m site --user-site )/gauge_api_steps\n ```\n* 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.\\\n Example on a Mac:\n ```\n STEP_IMPL_DIR = /Users/<user>/Library/Python/3.10/lib/python/site-packages/gauge_api_steps, step_impl\n ```\n* Reload Visual Studio Code\n* Write a new scenario in `specs/example.spec`. VSC offers **auto-completion**\n\n## Installation\n\nThis module can be installed from source:\n\n```shell\ncd path/to/gauge-api-steps\npip install --user .\n```\n\nOr the latest package can be downloaded and installed from [PyPi](https://pypi.org/project/gauge-api-steps):\n\n```shell\npip install gauge-api-steps --user --upgrade\n```\n\n## Development\n\nWhen coding on this project, unit tests can be executed like this:\n\n```shell\npython -m unittest discover -v -s tests/ -p 'test_*.py'\n```\n\n[Contributions are welcome](https://github.com/IBM/gauge-api-steps/tree/master/docs/CONTRIBUTING.md).\n\n## Expressions in Parameters\n\n### Property Placeholders\n\nStep 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.\n\n### Mathematical Expressions\n\nMathematical expressions can also be evaluated. For example: `#{5 + 5 * 5}` is evaluated to `30`.\n\nIt is possible to combine the two features. Placeholder substitution takes place before mathematical expression evaluation.\n\n### Functional Expressions\n\nFunctional expressions will generate a result during step execution. There are different expressions:\n* UUID generation: `!{uuid}`\n* 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](https://docs.python.org/3.10/library/time.html#time.strftime).\n* Load content from text file: `!{file:resources/file.json}` The File must be inside the project directory.\n* Load graphQL from file: `!{gql:resources/file.gql}` or `!{graphql:resources/file.gql}` This will automatically generate the JSON format, that can be used in the request body.\n\n\n### Expression Examples\n\nNote that the property expressions start with `$`, mathematical expressions with `#`, and functional expressions with `!`.\n\nThe property \"homepage_url\" can be defined in _env/default/test.properties_ like this:\n\n> homepage_url = https://my-app.net\n\n> \\* Request \"GET\" \"\\${homepage_url}/home\"\n\n> \\* Print \"5 + 6 = #{5 + 6}\"\n\nIt is also possible to define a property in a step:\n\n> \\* Store \"addend\" \"5\"\n\n> \\* Print \"5 + 5 * 5 = #{$addend + 5 * 5}\"\n\nAnd also to create new properties from old:\n\n> \\* Store \"new\\_url\" \"${base_url}/id=!{uuid}&created=!{time}\"\n\n> \\* Print \"!{uuid}\"\n\n> \\* Print \"!{time}\"\n\n> \\* Print \"!{time:%Y-%m-%d}\"\n\n> \\* With body \"!{file:resources/request.json}\"\n\n> \\* With body \"!{file:resources/request.xml}\"\n\n> \\* With body \"!{gql:resources/request.gql}\"\n\n### Internal Placeholders\n\nFollowing placeholders are used internally to store data over multiple steps:\n\n* \\_opener\n* \\_response\\_csrf\\_header\n* \\_request\\_csrf\\_header\n* \\_csrf\\_value\n* \\_body\n* \\_response\n* \\_headers\n\nIt is possible to access and manipulate them with certain steps.\n\n## Configuration\n\nThe Configuration follows the [Gauge configuration](https://docs.gauge.org/configuration.html?os=linux&language=python&ide=vscode) approach.\nSome behaviour can be determined with properties.\n\n[Configuration Overview](https://github.com/IBM/gauge-api-steps/tree/master/docs/CONFIG.md)\n\n## Maintainers\n\n[Maintainers](https://github.com/IBM/gauge-api-steps/tree/master/docs/MAINTAINERS.md)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Provides steps for a Gauge project, that runs tests against APIs",
"version": "0.20",
"project_urls": {
"Homepage": "https://github.com/IBM/gauge-api-steps"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8f5a8ca01a72d6455f9c9c222e333360be9584fa5369f7f4cebd89412b09d6cd",
"md5": "88beba6499342a7535b5d6a3cff9ee9a",
"sha256": "2e1acfa45bf295d172857893d659cc03969139779c3dfaeaf9ad76789dd107ac"
},
"downloads": -1,
"filename": "gauge_api_steps-0.20-py3-none-any.whl",
"has_sig": false,
"md5_digest": "88beba6499342a7535b5d6a3cff9ee9a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 13357,
"upload_time": "2024-10-15T12:34:01",
"upload_time_iso_8601": "2024-10-15T12:34:01.827618Z",
"url": "https://files.pythonhosted.org/packages/8f/5a/8ca01a72d6455f9c9c222e333360be9584fa5369f7f4cebd89412b09d6cd/gauge_api_steps-0.20-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d331dfa2b9f49db7276f917d6d089bdda074d9202b8f835e339c6c21e54e7772",
"md5": "7b65eec77085c29fe29811cabcaf29aa",
"sha256": "5a1e23a2558a5c0181aaa906ce25ff1b34a932c1633e86a83214e29e9a0a39f7"
},
"downloads": -1,
"filename": "gauge-api-steps-0.20.tar.gz",
"has_sig": false,
"md5_digest": "7b65eec77085c29fe29811cabcaf29aa",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 13982,
"upload_time": "2024-10-15T12:34:03",
"upload_time_iso_8601": "2024-10-15T12:34:03.556948Z",
"url": "https://files.pythonhosted.org/packages/d3/31/dfa2b9f49db7276f917d6d089bdda074d9202b8f835e339c6c21e54e7772/gauge-api-steps-0.20.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-15 12:34:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "IBM",
"github_project": "gauge-api-steps",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "gauge-api-steps"
}
JSON
