| Name | robotframework-nl JSON |
| Version |
3.0.0
JSON |
| download |
| home_page | |
| Summary | robotnl is a proving ground to boost Robot framework closer to Natural Language. |
| upload_time | 2024-01-11 10:18:13 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.8 |
| license | BSD 3-Clause License Copyright (c) 2021, J. Foederer All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| keywords |
robotframework
robot
testing
dsl
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# robotframeworkNL - the oneliner
robotframeworkNL is a proving ground to boost Robot framework closer to Natural Language.
## Introduction
This project is an extension to [Robot framework](https://robotframework.org/) and although [Robot framework](https://robotframework.org/) made a very good step towards the goals of [keyword-driven testing ](https://en.wikipedia.org/wiki/Keyword-driven_testing) to make it readable for all stakeholders, there is still quite a lot of syntax involved that keeps test cases from really staying concise and to-the-point. In this project we will be introducing concepts to lift [Robot framework](https://robotframework.org/) to an even higher level.
This second release introduces ``inline keywords`` and a set of ``Check that`` keywords that help to vastly reduce the amount of ``${...}`` cluttering in your test cases. Combining these concepts helps to write a cleaner [Domain Specific Language](https://en.wikipedia.org/wiki/Domain-specific_language) around your [domain vocabulary](https://en.wikipedia.org/wiki/Jargon).
## Installation
The recommended installation method is using [pip](http://pip-installer.org)
pip install --upgrade robotframework-nl
After installation include `robotnl` as library in your robot file to get access to the new keywords.
## Features
### Inline keywords
We use the term *inline keyword* when a keyword is used as an argument to another keyword. In this case the inline keyword must return a value, which will then be used as the actual argument. Consider this basic example where a keywords exists by the name *'twelve'* that just returns the number 12, which is then used in an action keyword operating an elevator.
|**Using inline keyword**||
|---|---|
| Request elevator floor | twelve |
|**Traditional Robot**||
| ${floor to request}= | twelve |
| Request elevator floor | ${floor to request} |
To add support for inline keywords to your keywords, decorate your keyword with the `@keyword` decorator from the `robotnl` library, instead of using the one from `robot.api.deco`.
```python
from robotnl import keyword
class my_elevator:
@keyword(name="Request elevator floor")
def handle_floor_request(target_floor):
...
```
Inline keywords are limited to a single *cell* in Robot. This means that keywords that are used inline, cannot take any positional arguments when used inline. Embedded arguments are considered part of the same cell and do not have that limitation.
Inline keywords are detected and processed at runtime. If a keyword is found that matches the argument's text, then that keyword will be executed and its return value used as the actual argument. When editing test cases, keyword highlighting can show which arguments are keywords when using a dynamic IDE like [RIDE](https://github.com/robotframework/RIDE/wiki) (one that loads the keyword libraries into the IDE). Static editors will not be able to show this information, due to the runtime evaluation.
### Check that
Using *Check that* keywords offers a large reduction in the need for variables in your test case and ``less variables = less ${} syntax``! It also encourages the use of the [Doobcheck](#doobcheck) principle, which is an easy way to create maintainable keyword libraries.
|**It let's you write**||||||
|---|---|---|---|---|---|
| Check that | Two times | 6 | equals | Three times | 4 |
|**instead of**||||||
| ${calculation 1}= | Two times | ${6} ||||
| ${calculation 2}= | Three times | ${4} ||||
| Should be equal | ${calculation 1} | ${calculation 2} ||||
### Time constraints
*Check that* offers support for executing checks that may take some time to complete. When using the optional `within` argument, followed by a time duration, *Check that* will apply *smart polling* to re-evaluate the expression and the keywords during the given period. Specifying the time limit is done using the standard [Robot Framework time format](https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#toc-entry-176). It is advised to use a realistic time duration. This sets the correct expectation for the reader and helps robotnl optimise its polling algorithm.
|**Example using time constaints**||||||
|---|---|---|---|---|---|
| Request elevator at floor | 3 |||||
| Check that | elevator doors are closed | within | 20 seconds ||
| Check that | current elevator floor | equals | 3 | within | 1 minute |
### Hybrid manual testing
To manually interact with your automated test run during testing or test case development, robotnl offers the *Check manual* and *Check interactive* keywords. These keywords can be included at any point in the test case to suspend the test run at the current position for user input.
***Check Manual*** allows asking the tester a question. The question typically requests manual verification of an expected outcome. The answer will PASS or FAIL the test case, which is also reflected in the test report.
***Check interactive*** prompts the user to input a keyword. You have access to all build-in, user and library keywords available to that test case. The keyword is executed, but failures will not fail the test case nor abort execution. This is ideal for trying out keywords and keyword variations without having to restart the test run every time.
### Keyword documentation
Full documentation of the keywords offered by `robotnl` can be found here:
[Link to keyword documentation](https://jfoederer.github.io/robotframeworkNL/robotnl-libdoc.html)
Keyword documentation is in [libdoc](http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#libdoc) format, making it also directly available via intellisense in IDEs, like [RIDE](https://github.com/robotframework/RIDE/wiki).
## Proposed improvements
* Option to mark keywords as *operator keywords*
This improvement affects the *Check that* keywords and will remove the limitations on using inline keywords as arguments to operands. Without annotating operator keywords as such, it is not always possible to detect which keywords are intended as arguments to the operand and which one should be the operator.
* Explicit literal support
Include a special annotation to express that something is not a keyword. For the odd case that a literal text needed as argument, also exists as a keyword. Alternativly the keyword receiving the argument can also use Robot's default keyword decorator.
## Doobcheck
Doobcheck is short for Do-Observe-Check and the idea is simple, yet effective. Any keyword should have just one of these purposes, never more.
- Do keywords invoke an action. These keywords start with a verb and do not return anything.
- Observation keywords return information, without affecting state. These keywords typically start with a noun, the thing that is being observed.
- Check keywords are used for verifying information, typically using the result of an observation-keyword and an expected value. This `robotnl` library offers generic [Check keywords](#check-that) and operators. You can build new operator keywords in your own libraries to support any check you will ever need.
Raw data
{
"_id": null,
"home_page": "",
"name": "robotframework-nl",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "robotframework,robot,testing,dsl",
"author": "",
"author_email": "Johan Foederer <github@famfoe.nl>",
"download_url": "https://files.pythonhosted.org/packages/23/34/83cb3ac5c6f43a294f94570d484b3ae4fac798a3489e0e66962642f4b395/robotframework-nl-3.0.0.tar.gz",
"platform": null,
"description": "# robotframeworkNL - the oneliner\r\nrobotframeworkNL is a proving ground to boost Robot framework closer to Natural Language.\r\n\r\n## Introduction\r\nThis project is an extension to [Robot framework](https://robotframework.org/) and although [Robot framework](https://robotframework.org/) made a very good step towards the goals of [keyword-driven testing ](https://en.wikipedia.org/wiki/Keyword-driven_testing) to make it readable for all stakeholders, there is still quite a lot of syntax involved that keeps test cases from really staying concise and to-the-point. In this project we will be introducing concepts to lift [Robot framework](https://robotframework.org/) to an even higher level.\r\n\r\nThis second release introduces ``inline keywords`` and a set of ``Check that`` keywords that help to vastly reduce the amount of ``${...}`` cluttering in your test cases. Combining these concepts helps to write a cleaner [Domain Specific Language](https://en.wikipedia.org/wiki/Domain-specific_language) around your [domain vocabulary](https://en.wikipedia.org/wiki/Jargon).\r\n\r\n## Installation\r\nThe recommended installation method is using [pip](http://pip-installer.org)\r\n\r\n pip install --upgrade robotframework-nl\r\n\r\nAfter installation include `robotnl` as library in your robot file to get access to the new keywords.\r\n\r\n## Features\r\n\r\n### Inline keywords\r\n\r\nWe use the term *inline keyword* when a keyword is used as an argument to another keyword. In this case the inline keyword must return a value, which will then be used as the actual argument. Consider this basic example where a keywords exists by the name *'twelve'* that just returns the number 12, which is then used in an action keyword operating an elevator.\r\n\r\n|**Using inline keyword**||\r\n|---|---|\r\n| Request elevator floor | twelve |\r\n|**Traditional Robot**||\r\n| ${floor to request}= | twelve |\r\n| Request elevator floor | ${floor to request} |\r\n\r\nTo add support for inline keywords to your keywords, decorate your keyword with the `@keyword` decorator from the `robotnl` library, instead of using the one from `robot.api.deco`.\r\n\r\n```python\r\nfrom robotnl import keyword\r\n\r\n class my_elevator:\r\n @keyword(name=\"Request elevator floor\")\r\n def handle_floor_request(target_floor):\r\n ...\r\n```\r\n\r\nInline keywords are limited to a single *cell* in Robot. This means that keywords that are used inline, cannot take any positional arguments when used inline. Embedded arguments are considered part of the same cell and do not have that limitation.\r\n\r\nInline keywords are detected and processed at runtime. If a keyword is found that matches the argument's text, then that keyword will be executed and its return value used as the actual argument. When editing test cases, keyword highlighting can show which arguments are keywords when using a dynamic IDE like [RIDE](https://github.com/robotframework/RIDE/wiki) (one that loads the keyword libraries into the IDE). Static editors will not be able to show this information, due to the runtime evaluation.\r\n\r\n### Check that\r\n\r\nUsing *Check that* keywords offers a large reduction in the need for variables in your test case and ``less variables = less ${} syntax``! It also encourages the use of the [Doobcheck](#doobcheck) principle, which is an easy way to create maintainable keyword libraries.\r\n\r\n|**It let's you write**||||||\r\n|---|---|---|---|---|---|\r\n| Check that | Two times | 6 | equals | Three times | 4 |\r\n|**instead of**||||||\r\n| ${calculation 1}= | Two times | ${6} ||||\r\n| ${calculation 2}= | Three times | ${4} ||||\r\n| Should be equal | ${calculation 1} | ${calculation 2} ||||\r\n\r\n### Time constraints\r\n\r\n*Check that* offers support for executing checks that may take some time to complete. When using the optional `within` argument, followed by a time duration, *Check that* will apply *smart polling* to re-evaluate the expression and the keywords during the given period. Specifying the time limit is done using the standard [Robot Framework time format](https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#toc-entry-176). It is advised to use a realistic time duration. This sets the correct expectation for the reader and helps robotnl optimise its polling algorithm.\r\n\r\n|**Example using time constaints**||||||\r\n|---|---|---|---|---|---|\r\n| Request elevator at floor | 3 |||||\r\n| Check that | elevator doors are closed | within | 20 seconds ||\r\n| Check that | current elevator floor | equals | 3 | within | 1 minute |\r\n\r\n### Hybrid manual testing\r\n\r\nTo manually interact with your automated test run during testing or test case development, robotnl offers the *Check manual* and *Check interactive* keywords. These keywords can be included at any point in the test case to suspend the test run at the current position for user input.\r\n\r\n***Check Manual*** allows asking the tester a question. The question typically requests manual verification of an expected outcome. The answer will PASS or FAIL the test case, which is also reflected in the test report.\r\n\r\n***Check interactive*** prompts the user to input a keyword. You have access to all build-in, user and library keywords available to that test case. The keyword is executed, but failures will not fail the test case nor abort execution. This is ideal for trying out keywords and keyword variations without having to restart the test run every time.\r\n\r\n### Keyword documentation\r\n\r\nFull documentation of the keywords offered by `robotnl` can be found here: \r\n[Link to keyword documentation](https://jfoederer.github.io/robotframeworkNL/robotnl-libdoc.html)\r\n\r\nKeyword documentation is in [libdoc](http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#libdoc) format, making it also directly available via intellisense in IDEs, like [RIDE](https://github.com/robotframework/RIDE/wiki).\r\n\r\n## Proposed improvements\r\n\r\n* Option to mark keywords as *operator keywords* \r\n This improvement affects the *Check that* keywords and will remove the limitations on using inline keywords as arguments to operands. Without annotating operator keywords as such, it is not always possible to detect which keywords are intended as arguments to the operand and which one should be the operator.\r\n* Explicit literal support \r\n Include a special annotation to express that something is not a keyword. For the odd case that a literal text needed as argument, also exists as a keyword. Alternativly the keyword receiving the argument can also use Robot's default keyword decorator.\r\n\r\n## Doobcheck\r\n\r\nDoobcheck is short for Do-Observe-Check and the idea is simple, yet effective. Any keyword should have just one of these purposes, never more.\r\n\r\n- Do keywords invoke an action. These keywords start with a verb and do not return anything.\r\n- Observation keywords return information, without affecting state. These keywords typically start with a noun, the thing that is being observed.\r\n- Check keywords are used for verifying information, typically using the result of an observation-keyword and an expected value. This `robotnl` library offers generic [Check keywords](#check-that) and operators. You can build new operator keywords in your own libraries to support any check you will ever need.\r\n",
"bugtrack_url": null,
"license": "BSD 3-Clause License Copyright (c) 2021, J. Foederer All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. ",
"summary": "robotnl is a proving ground to boost Robot framework closer to Natural Language.",
"version": "3.0.0",
"project_urls": {
"Homepage": "https://github.com/JFoederer/robotframeworkNL"
},
"split_keywords": [
"robotframework",
"robot",
"testing",
"dsl"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e2008702c3549c2504a7f825227c9455808081aeb574dd120caeadbf9c54bf1d",
"md5": "9a849caafe02dc45556d1a305d5afcc8",
"sha256": "a54d8ce67b9aae643d97e7485f2bbdf2aa9f3d083b28b19b1f8d0544c54c10ca"
},
"downloads": -1,
"filename": "robotframework_nl-3.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9a849caafe02dc45556d1a305d5afcc8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 17899,
"upload_time": "2024-01-11T10:18:12",
"upload_time_iso_8601": "2024-01-11T10:18:12.239820Z",
"url": "https://files.pythonhosted.org/packages/e2/00/8702c3549c2504a7f825227c9455808081aeb574dd120caeadbf9c54bf1d/robotframework_nl-3.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "233483cb3ac5c6f43a294f94570d484b3ae4fac798a3489e0e66962642f4b395",
"md5": "0db4ec228ef5ed5d19ad9e78781a10be",
"sha256": "2543ca4272d2eb2dc6979d856f0748c9ba308ee9d1ec048adbb3ea990e7b81e9"
},
"downloads": -1,
"filename": "robotframework-nl-3.0.0.tar.gz",
"has_sig": false,
"md5_digest": "0db4ec228ef5ed5d19ad9e78781a10be",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 12983,
"upload_time": "2024-01-11T10:18:13",
"upload_time_iso_8601": "2024-01-11T10:18:13.519466Z",
"url": "https://files.pythonhosted.org/packages/23/34/83cb3ac5c6f43a294f94570d484b3ae4fac798a3489e0e66962642f4b395/robotframework-nl-3.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-11 10:18:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "JFoederer",
"github_project": "robotframeworkNL",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "robotframework-nl"
}
