# RESTinstance (1.4.4)
[Robot Framework](http://robotframework.org) library for RESTful JSON APIs
[Keyword Documentation](https://asyrjasalo.github.io/RESTinstance)
## Advantages
1. **RESTinstance relies on Robot Framework's language-agnostic, clean
and minimal syntax, for API tests.** It is neither tied to any
particular programming language nor development framework. Using
RESTinstance requires little, if any, programming knowledge. It
builts on long-term technologies with well established communities,
such as HTTP, JSON (Schema), Swagger/OpenAPI and Robot Framework.
2. **It validates JSON using JSON Schema, guiding you to write API
tests to base on properties** rather than on specific values (e.g.
"email must be valid" vs "email is foo@bar.com"). This approach
reduces test maintenance when the values responded by the API are
prone to change. Although values are not required, you can still
test them whenever they make sense (e.g. GET response body from one
endpoint, then POST some of its values to another endpoint and
verify the results).
3. **It generates JSON Schema for requests and responses automatically,
and the schema gets more accurate by your tests.** Output the schema
to a file and reuse it as expectations to test the other methods, as
most of them respond similarly with only minor differences. Or
extend the schema further to a full Swagger spec (version 2.0,
OpenAPI 3.0 also planned), which RESTinstance can test requests and
responses against. All this leads to reusability, getting great test
coverage with minimum number of keystrokes and very clean tests.
## Installation
Install and upgrade [from PyPi](https://pypi.org/project/RESTinstance):
pip install --upgrade RESTinstance
## Usage
See [the keyword documentation](https://asyrjasalo.github.io/RESTinstance).
### Quick start
1. Create two new empty directories, `atest` and `results`.
2. Create a new file `atest/YOURNAME.robot` with the content:
``` robotframework
*** Settings ***
Library REST https://jsonplaceholder.typicode.com
Documentation Test data can be read from variables and files.
... Both JSON and Python type systems are supported for inputs.
... Every request creates a so-called instance. Can be `Output`.
... Most keywords are effective only for the last instance.
... Initial schemas are autogenerated for request and response.
... You can make them more detailed by using assertion keywords.
... The assertion keywords correspond to the JSON types.
... They take in either path to the property or a JSONPath query.
... Using (enum) values in tests optional. Only type is required.
... All the JSON Schema validation keywords are also supported.
... Thus, there is no need to write any own validation logic.
... Not a long path from schemas to full Swagger/OpenAPI specs.
... The persistence of the created instances is the test suite.
... Use keyword `Rest instances` to output the created instances.
*** Variables ***
${json} { "id": 11, "name": "Gil Alexander" }
&{dict} name=Julie Langford
*** Test Cases ***
GET an existing user, notice how the schema gets more accurate
GET /users/1 # this creates a new instance
Output schema response body
Object response body # values are fully optional
Integer response body id 1
String response body name Leanne Graham
[Teardown] Output schema # note the updated response schema
GET existing users, use JSONPath for very short but powerful queries
GET /users?_limit=5 # further assertions are to this
Array response body
Integer $[0].id 1 # first id is 1
String $[0]..lat -37.3159 # any matching child
Integer $..id maximum=5 # multiple matches
[Teardown] Output $[*].email # outputs all emails as an array
POST with valid params to create a new user, can be output to a file
POST /users ${json}
Integer response status 201
[Teardown] Output response body ${OUTPUTDIR}/new_user.demo.json
PUT with valid params to update the existing user, values matter here
PUT /users/2 { "isCoding": true }
Boolean response body isCoding true
PUT /users/2 { "sleep": null }
Null response body sleep
PUT /users/2 { "pockets": "", "money": 0.02 }
String response body pockets ${EMPTY}
Number response body money 0.02
Missing response body moving # fails if property moving exists
PATCH with valid params, reusing response properties as a new payload
&{res}= GET /users/3
String $.name Clementine Bauch
PATCH /users/4 { "name": "${res.body['name']}" }
String $.name Clementine Bauch
PATCH /users/5 ${dict}
String $.name ${dict.name}
DELETE the existing successfully, save the history of all requests
DELETE /users/6 # status can be any of the below
Integer response status 200 202 204
Rest instances ${OUTPUTDIR}/all.demo.json # all the instances so far
```
3. Make JSON API testing great again:
```
robot --outputdir results atest/
```
## Contributing
Kindly create an [issue](https://github.com/asyrjasalo/RESTinstance/issues)
and then create a pull request. See `CONTRIBUTING.md` for that.
Install [PDM](https://pdm-project.org/latest/):
python -m pip install --user pdm
Install dependencies:
pdm install
Acceptance tests require you starting [mountebank](https://www.mbtest.org)
`testapi/` in another terminal first:
pdm testenv
To run all tests:
pdm tests
You can debug mountebank requests and responses created by acceptance tests
at [localhost:2525](http://localhost:2525/imposters).
Arguments can be passed to `pytest` and `robot`, respectively:
pdm test -- test/<test_modulename>.py
pdm atest -- atest/<atest_suitefile>.robot
## Credits
RESTinstance is under
[LGPL-3.0 license](https://github.com/asyrjasalo/RESTinstance/blob/master/LICENSE.txt)
and is originally written by [Anssi Syrjäsalo](https://github.com/asyrjasalo).
It was first presented at the first [RoboCon](https://robocon.io), 2018.
Contributors:
- Eficode Ltd.
We use following Python excellence under the hood:
- [Flex](https://github.com/pipermerriam/flex), by Piper Merriam, for
Swagger 2.0 validation
- [GenSON](https://github.com/wolverdude/GenSON), by Jon "wolverdude"
Wolverton, for JSON Schema generator
- [jsonpath-ng](https://github.com/h2non/jsonpath-ng), by Tomas
Aparicio and Kenneth Knowles, for handling JSONPath queries
- [jsonschema](https://github.com/Julian/jsonschema), by Julian
Berman, for JSON Schema validator
- [pygments](http://pygments.org), by Georg Brandl et al., for JSON
syntax coloring
- [requests](https://github.com/requests/requests), by Kenneth Reitz
et al., for making HTTP requests
Raw data
{
"_id": null,
"home_page": null,
"name": "RESTinstance",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "robotframework, library, http, json, api",
"author": null,
"author_email": "Anssi Syrj\u00e4salo <opensource@syrjasalo.com>",
"download_url": "https://files.pythonhosted.org/packages/ee/c2/0c096c987b5bb720337fc0668084aa21c64b647e5a6b13acdb6cd851ad9e/restinstance-1.4.4.tar.gz",
"platform": null,
"description": "# RESTinstance (1.4.4)\n\n[Robot Framework](http://robotframework.org) library for RESTful JSON APIs\n\n[Keyword Documentation](https://asyrjasalo.github.io/RESTinstance)\n\n## Advantages\n\n1. **RESTinstance relies on Robot Framework's language-agnostic, clean\n and minimal syntax, for API tests.** It is neither tied to any\n particular programming language nor development framework. Using\n RESTinstance requires little, if any, programming knowledge. It\n builts on long-term technologies with well established communities,\n such as HTTP, JSON (Schema), Swagger/OpenAPI and Robot Framework.\n2. **It validates JSON using JSON Schema, guiding you to write API\n tests to base on properties** rather than on specific values (e.g.\n \"email must be valid\" vs \"email is foo@bar.com\"). This approach\n reduces test maintenance when the values responded by the API are\n prone to change. Although values are not required, you can still\n test them whenever they make sense (e.g. GET response body from one\n endpoint, then POST some of its values to another endpoint and\n verify the results).\n3. **It generates JSON Schema for requests and responses automatically,\n and the schema gets more accurate by your tests.** Output the schema\n to a file and reuse it as expectations to test the other methods, as\n most of them respond similarly with only minor differences. Or\n extend the schema further to a full Swagger spec (version 2.0,\n OpenAPI 3.0 also planned), which RESTinstance can test requests and\n responses against. All this leads to reusability, getting great test\n coverage with minimum number of keystrokes and very clean tests.\n\n## Installation\n\nInstall and upgrade [from PyPi](https://pypi.org/project/RESTinstance):\n\n pip install --upgrade RESTinstance\n\n## Usage\n\nSee [the keyword documentation](https://asyrjasalo.github.io/RESTinstance).\n\n### Quick start\n\n1. Create two new empty directories, `atest` and `results`.\n2. Create a new file `atest/YOURNAME.robot` with the content:\n\n``` robotframework\n*** Settings ***\nLibrary REST https://jsonplaceholder.typicode.com\nDocumentation Test data can be read from variables and files.\n... Both JSON and Python type systems are supported for inputs.\n... Every request creates a so-called instance. Can be `Output`.\n... Most keywords are effective only for the last instance.\n... Initial schemas are autogenerated for request and response.\n... You can make them more detailed by using assertion keywords.\n... The assertion keywords correspond to the JSON types.\n... They take in either path to the property or a JSONPath query.\n... Using (enum) values in tests optional. Only type is required.\n... All the JSON Schema validation keywords are also supported.\n... Thus, there is no need to write any own validation logic.\n... Not a long path from schemas to full Swagger/OpenAPI specs.\n... The persistence of the created instances is the test suite.\n... Use keyword `Rest instances` to output the created instances.\n\n\n*** Variables ***\n${json} { \"id\": 11, \"name\": \"Gil Alexander\" }\n&{dict} name=Julie Langford\n\n\n*** Test Cases ***\nGET an existing user, notice how the schema gets more accurate\n GET /users/1 # this creates a new instance\n Output schema response body\n Object response body # values are fully optional\n Integer response body id 1\n String response body name Leanne Graham\n [Teardown] Output schema # note the updated response schema\n\nGET existing users, use JSONPath for very short but powerful queries\n GET /users?_limit=5 # further assertions are to this\n Array response body\n Integer $[0].id 1 # first id is 1\n String $[0]..lat -37.3159 # any matching child\n Integer $..id maximum=5 # multiple matches\n [Teardown] Output $[*].email # outputs all emails as an array\n\nPOST with valid params to create a new user, can be output to a file\n POST /users ${json}\n Integer response status 201\n [Teardown] Output response body ${OUTPUTDIR}/new_user.demo.json\n\nPUT with valid params to update the existing user, values matter here\n PUT /users/2 { \"isCoding\": true }\n Boolean response body isCoding true\n PUT /users/2 { \"sleep\": null }\n Null response body sleep\n PUT /users/2 {\u00a0\"pockets\": \"\", \"money\": 0.02 }\n String response body pockets ${EMPTY}\n Number response body money 0.02\n Missing response body moving # fails if property moving exists\n\nPATCH with valid params, reusing response properties as a new payload\n &{res}= GET /users/3\n String $.name Clementine Bauch\n PATCH /users/4 { \"name\": \"${res.body['name']}\" }\n String $.name Clementine Bauch\n PATCH /users/5 ${dict}\n String $.name ${dict.name}\n\nDELETE the existing successfully, save the history of all requests\n DELETE /users/6 # status can be any of the below\n Integer response status 200 202 204\n Rest instances ${OUTPUTDIR}/all.demo.json # all the instances so far\n```\n\n3. Make JSON API testing great again:\n```\nrobot --outputdir results atest/\n```\n\n## Contributing\n\nKindly create an [issue](https://github.com/asyrjasalo/RESTinstance/issues)\nand then create a pull request. See `CONTRIBUTING.md` for that.\n\nInstall [PDM](https://pdm-project.org/latest/):\n\n python -m pip install --user pdm\n\nInstall dependencies:\n\n pdm install\n\nAcceptance tests require you starting [mountebank](https://www.mbtest.org)\n`testapi/` in another terminal first:\n\n pdm testenv\n\nTo run all tests:\n\n pdm tests\n\nYou can debug mountebank requests and responses created by acceptance tests\nat [localhost:2525](http://localhost:2525/imposters).\n\nArguments can be passed to `pytest` and `robot`, respectively:\n\n pdm test -- test/<test_modulename>.py\n pdm atest -- atest/<atest_suitefile>.robot\n\n## Credits\n\nRESTinstance is under\n[LGPL-3.0 license](https://github.com/asyrjasalo/RESTinstance/blob/master/LICENSE.txt)\nand is originally written by [Anssi Syrj\u00e4salo](https://github.com/asyrjasalo).\n\nIt was first presented at the first [RoboCon](https://robocon.io), 2018.\n\nContributors:\n\n- Eficode Ltd.\n\nWe use following Python excellence under the hood:\n\n- [Flex](https://github.com/pipermerriam/flex), by Piper Merriam, for\nSwagger 2.0 validation\n- [GenSON](https://github.com/wolverdude/GenSON), by Jon \"wolverdude\"\nWolverton, for JSON Schema generator\n- [jsonpath-ng](https://github.com/h2non/jsonpath-ng), by Tomas\nAparicio and Kenneth Knowles, for handling JSONPath queries\n- [jsonschema](https://github.com/Julian/jsonschema), by Julian\nBerman, for JSON Schema validator\n- [pygments](http://pygments.org), by Georg Brandl et al., for JSON\nsyntax coloring\n- [requests](https://github.com/requests/requests), by Kenneth Reitz\net al., for making HTTP requests\n",
"bugtrack_url": null,
"license": "LGPLv3",
"summary": "Robot Framework library for RESTful JSON APIs",
"version": "1.4.4",
"project_urls": {
"Documentation": "https://asyrjasalo.github.io/RESTinstance",
"Homepage": "https://pypi.org/project/RESTinstance",
"Repository": "https://github.com/asyrjasalo/RESTinstance"
},
"split_keywords": [
"robotframework",
" library",
" http",
" json",
" api"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "dc6e91b469ae898d4cfda85ed8f4f4a305edd6850285d961028dfe603764a783",
"md5": "bd7c6ed7f944e4f43ad9c37c0ff0a1a0",
"sha256": "bbbc7a05efdcf10be4258072212befa83cc625eb544d5a2c2518208da3340206"
},
"downloads": -1,
"filename": "RESTinstance-1.4.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bd7c6ed7f944e4f43ad9c37c0ff0a1a0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 23414,
"upload_time": "2024-07-29T10:05:45",
"upload_time_iso_8601": "2024-07-29T10:05:45.721262Z",
"url": "https://files.pythonhosted.org/packages/dc/6e/91b469ae898d4cfda85ed8f4f4a305edd6850285d961028dfe603764a783/RESTinstance-1.4.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "eec20c096c987b5bb720337fc0668084aa21c64b647e5a6b13acdb6cd851ad9e",
"md5": "5187b9ee994b4c57beaaa76f476bd54b",
"sha256": "a43f3e204cee186bbf2c74d2e009c6f56c361209817073bf5ad7cfaf6ef88c8a"
},
"downloads": -1,
"filename": "restinstance-1.4.4.tar.gz",
"has_sig": false,
"md5_digest": "5187b9ee994b4c57beaaa76f476bd54b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 27585,
"upload_time": "2024-07-29T10:05:47",
"upload_time_iso_8601": "2024-07-29T10:05:47.681068Z",
"url": "https://files.pythonhosted.org/packages/ee/c2/0c096c987b5bb720337fc0668084aa21c64b647e5a6b13acdb6cd851ad9e/restinstance-1.4.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-29 10:05:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "asyrjasalo",
"github_project": "RESTinstance",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "restinstance"
}
JSON
