diff options
Diffstat (limited to 'python-restinstance.spec')
| -rw-r--r-- | python-restinstance.spec | 1216 |
1 files changed, 1216 insertions, 0 deletions
diff --git a/python-restinstance.spec b/python-restinstance.spec new file mode 100644 index 0000000..f243a68 --- /dev/null +++ b/python-restinstance.spec @@ -0,0 +1,1216 @@ +%global _empty_manifest_terminate_build 0 +Name: python-RESTinstance +Version: 1.3.0 +Release: 1 +Summary: Robot Framework library for RESTful JSON APIs +License: Apache License 2.0 +URL: https://github.com/asyrjasalo/RESTinstance +Source0: https://mirrors.nju.edu.cn/pypi/web/packages/06/ea/d984d5e17d7809203a0bce8150cd3490edf60fa957afef9e5d3f7030a6e5/RESTinstance-1.3.0.tar.gz +BuildArch: noarch + +Requires: python3-docutils +Requires: python3-flex +Requires: python3-GenSON +Requires: python3-jsonpath-ng +Requires: python3-jsonschema +Requires: python3-pygments +Requires: python3-pytz +Requires: python3-requests +Requires: python3-robotframework +Requires: python3-tzlocal + +%description +# RESTinstance + +[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 + +On 3.6, 3.7 you can install and upgrade +[from PyPi](https://pypi.org/project/RESTinstance): + + python3 -m venv venv + source venv/bin/activate + pip install --upgrade RESTinstance + +On 2.7 series the package works as well, but using 2.7 is +[not preferred 2020 onwards](https://pythonclock.org/): + + pip install --user --upgrade virtualenv + virtualenv venv + source venv/bin/activate + pip install --upgrade RESTinstance + +These also install [Robot Framework](https://pypi.org/project/robotframework) +if you do not have it already. + + + +## Usage + +There is a +[step-by-step tutorial](https://github.com/asyrjasalo/RESTinstance/blob/master/examples) +in the making, best accompanied with +[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 + +Bug reports and feature requests are tracked in +[GitHub](https://github.com/asyrjasalo/RESTinstance/issues). +We do respect pull request(er)s. + +### Local development + +The logic is detaching the enving from system level (dependencies) as following: +1. We use [pyenv](https://github.com/pyenv/pyenv) to manage n Pythons user-wide. +2. With Pyenv installed Pythons, we never mess with the system's default Python. +3. We ended up to [Nox](https://nox.thea.codes/en/stable/) after evaluating +Bash scripts, `make`, `invoke` and `tox` to achieve automated virtualenving. + +To understand the first two of the practices, these are worth reading: +- [Real Python's intro to pyenv](https://realpython.com/intro-to-pyenv) +- [Real Python's virtualenvs primer](https://realpython.com/python-virtual-environments-a-primer/) +- [virtualenv compatibility with the stdlib venv module](https://virtualenv.pypa.io/en/latest/reference/#compatibility-with-the-stdlib-venv-module) + +Third, unlike Tox, Nox uses Python file (`noxfile.py`) for configuration, yet: +- Supports multiple Python versions, each session is ran on some `pythonX.X`. +- A session is a single virtualenv which is stored in `.venv/<session_name>`. +- Every `nox` recreates session, thus virtualenv, unless `reuse_venv=True`. + +### Python versioning w/ pyenv + +The pyenv setup works on OS X and on the common Linux distros out of the box: + + curl https://pyenv.run | bash + export PATH="$HOME/.pyenv/bin:$PATH" + eval "$(pyenv init -)" + +The first script installs it user-wide, thus it never requires `sudo` rights. + +If you are on Windows, using pyenv might or might not be an option. Regardless, +you want to check [pyenv-win](https://github.com/pyenv-win/pyenv-win) instead. + +We test, develop, build and publish on Python 3.6.9, and use venvs as preferred: + + git clone git@github.com:asyrjasalo/RESTinstance.git + cd RESTinstance + pyenv install --skip-existing 3.6.9 && pyenv rehash + python3 -m venv .venv/dev + source .venv/dev/bin/activate + pip install -e . + +### Automated venving w/ Nox + +Nox automates handling `.venv/<task>`s for workflows, that on Windows as well: + + pip install --upgrade nox + +The actual tasks are defined in `noxfile.py`, as well as our settings like: +- The default Python interpreter to run all the development tasks is `python3.6` +- We explicitly use [venv module](https://docs.python.org/3/library/venv.html) +now for virtualenving, as we develop on Python >= 3.3 anyway +- Whether a new virtualenv is always recreated when the respective task is run +(which is default for most of our tasks) + +Session is a task, running in the `.venv/<task>`. To list all possible sessions: + + nox -l + +Sessions defined in `RESTinstance/noxfile.py`: + + * test -> Run development tests for the package. + - testenv -> Run development server for acceptance tests. + * atest -> Run acceptance tests for the project. + - docs -> Regenerate documentation for the project. + - black -> Reformat/unify/"blacken" Python source code in-place. + - prospector -> Run various static analysis tools for the package. + - build -> Build sdist and wheel dists. + - release_testpypi -> Publish dist/* to TestPyPI. + - install_testpypi -> Install the latest (pre-)release from TestPyPI. + - release -> Tag, build and publish a new release to PyPI. + - install -> Install the latest release from PyPI. + - clean -> Remove all .venv's, build files and caches in the directory. + +Sessions marked with `*` are selected, sessions marked with `-` are skipped. + +That is, to run both `test`s and `atest`s: + + nox + +Session `nox -s atest` assumes you have started `testapi/` on +[mountebank](https://www.mbtest.org): + + nox -s testenv + +Running the above assumes you have `node` (>= 6) installed in your system. + +After started, you can debug requests and responses by tests in web browser at +[localhost:2525](http://localhost:2525/imposters). + +Both `nox -s test` and `nox -s atest` allow passing arguments to `pytest` +and `robot`, respectively: + + nox -s test -- test/<test_modulename>.py + nox -s atest -- atest/<atest_suitedir>/<atest_suitefile>.robot + +You know, having a virtualenv even for generating `docs/` - why not a bad idea: + + nox -s docs + +### Building and tagging a new version + +Remove all sessions (`.venv/`s) as well as temporary files in your working copy: + + nox -s clean + +Our PyPI distributions are known to work well on Python 3.7 and 2.7 series too: + + nox -s clean build + +We use [zest.releaser](https://github.com/zestsoftware/zest.releaser) for +versioning, tagging and building (universal) `bdist_wheel`s. + +It uses [twine](https://pypi.org/project/twine/) underneath to upload to PyPIs +securely over HTTPS, which can't be done with `python setup.py` commands. + +### Releasing to PyPIs + +This workflow is preferred for distributing a new (pre-)release to TestPyPI: + + nox -s test atest docs clean build release_testpypi install_testpypi + +If that installed well, all will be fine to let the final release to PyPI: + + nox -s release + +To install the latest release from PyPI, and in a dedicated venv of course: + + nox -s install + +### Shell additions + +For intermediate `nox` arguments usage, you'll advance by enabling +[shell completion](https://nox.thea.codes/en/stable/usage.html#shell-completion): + + eval "$(register-python-argcomplete nox)" + +On `zsh`, ensure you have bash compatibility enabled in `.zshrc` or similar: + + autoload -U bashcompinit + bashcompinit + +These completions likely do not work on vanilla PowerShell, but can be used on +[Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install-win10). + +### Unified Python editor/IDE linters + +Catching errors already write-time, regardless of the editor, is advantaged by +[Palantir's Python Language Server](https://github.com/palantir/python-language-server): + + python3 -m venv .venv/dev + source .venv/dev/bin/activate + pip install --upgrade python-language-server[all] + +Installing the all bundle, and the LSP plugin for your editor, enables to run +useful linters real-time, like: + +- Either `autopep8` or `black` (preferred) for automated code formatting +- `isort` for sorting code import statements +- McCabe for code complexity checking +- `mypy` for static type checking on Python 3 +- `pycodestyle` for coding style checking +- `pyflakes` for detecting various coding errors + +Remember to (auto-)start the language server on background via your editor. + +### pre-commit hooks + +We want our static analysis checks ran before code even ends up in a commit. + +Thus both `nox` and `nox -s test` commands bootstrap +[pre-commit](https://pre-commit.com/) hooks in your git working copy. + +The actual hooks are configured in `.pre-commit-commit.yaml`. + +### Ideas + +- export `mb` recorded responses to CI (pre-commit hook: `nox -s save_testenv`) +- change `nox -s testenv` to load the saved testenv -> rid of `--allowInjection` +- add CI (GitHub Actions? GitLab?) +- add Python types to pass `prospector --with-tool mypy` +- enable pre-commit hook for prospector + + + +## Credits + +RESTinstance is under +[Apache License 2.0](https://github.com/asyrjasalo/RESTinstance/blob/master/LICENSE) +and was originally written by [Anssi Syrjäsalo](https://github.com/asyrjasalo). + +It was first presented at the first [RoboCon](https://robocon.io), 2018. + +Contributors: + +- [jjwong](https://github.com/jjwong) for helping with keyword +documentation and examples (also check +[RESTinstance_starter_project](https://github.com/jjwong/RESTinstance_starter_project)) +- [Przemysław "sqilz" Hendel](https://github.com/sqilz) for using and +testing RESTinstance in early phase (also check +[RESTinstance-wrapper](https://github.com/sqilz/RESTinstance-wrapper)) +- [Vinh "vinhntb" Nguyen](https://github.com/vinhntb), +[#52](https://github.com/asyrjasalo/RESTinstance/pull/52). +- [Stavros "stdedos" Ntentos](https://github.com/stdedos), +[#75](https://github.com/asyrjasalo/RESTinstance/pull/75). +- [Nicholas "bollwyvl" Bollweg](https://github.com/bollwyvl), +[#84](https://github.com/asyrjasalo/RESTinstance/pull/84). +- [Trey Turner](https://github.com/treyturner), [#86](https://github.com/asyrjasalo/RESTinstance/pull/86) + +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, in terminal <span class="title-ref">Output</span> +- [requests](https://github.com/requests/requests), by Kenneth Reitz +et al., for making HTTP requests + +See +[requirements.txt](https://github.com/asyrjasalo/RESTinstance/blob/master/requirements.txt) +for all the direct run time dependencies. + +REST your mind, OSS got your back. + + + + +%package -n python3-RESTinstance +Summary: Robot Framework library for RESTful JSON APIs +Provides: python-RESTinstance +BuildRequires: python3-devel +BuildRequires: python3-setuptools +BuildRequires: python3-pip +%description -n python3-RESTinstance +# RESTinstance + +[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 + +On 3.6, 3.7 you can install and upgrade +[from PyPi](https://pypi.org/project/RESTinstance): + + python3 -m venv venv + source venv/bin/activate + pip install --upgrade RESTinstance + +On 2.7 series the package works as well, but using 2.7 is +[not preferred 2020 onwards](https://pythonclock.org/): + + pip install --user --upgrade virtualenv + virtualenv venv + source venv/bin/activate + pip install --upgrade RESTinstance + +These also install [Robot Framework](https://pypi.org/project/robotframework) +if you do not have it already. + + + +## Usage + +There is a +[step-by-step tutorial](https://github.com/asyrjasalo/RESTinstance/blob/master/examples) +in the making, best accompanied with +[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 + +Bug reports and feature requests are tracked in +[GitHub](https://github.com/asyrjasalo/RESTinstance/issues). +We do respect pull request(er)s. + +### Local development + +The logic is detaching the enving from system level (dependencies) as following: +1. We use [pyenv](https://github.com/pyenv/pyenv) to manage n Pythons user-wide. +2. With Pyenv installed Pythons, we never mess with the system's default Python. +3. We ended up to [Nox](https://nox.thea.codes/en/stable/) after evaluating +Bash scripts, `make`, `invoke` and `tox` to achieve automated virtualenving. + +To understand the first two of the practices, these are worth reading: +- [Real Python's intro to pyenv](https://realpython.com/intro-to-pyenv) +- [Real Python's virtualenvs primer](https://realpython.com/python-virtual-environments-a-primer/) +- [virtualenv compatibility with the stdlib venv module](https://virtualenv.pypa.io/en/latest/reference/#compatibility-with-the-stdlib-venv-module) + +Third, unlike Tox, Nox uses Python file (`noxfile.py`) for configuration, yet: +- Supports multiple Python versions, each session is ran on some `pythonX.X`. +- A session is a single virtualenv which is stored in `.venv/<session_name>`. +- Every `nox` recreates session, thus virtualenv, unless `reuse_venv=True`. + +### Python versioning w/ pyenv + +The pyenv setup works on OS X and on the common Linux distros out of the box: + + curl https://pyenv.run | bash + export PATH="$HOME/.pyenv/bin:$PATH" + eval "$(pyenv init -)" + +The first script installs it user-wide, thus it never requires `sudo` rights. + +If you are on Windows, using pyenv might or might not be an option. Regardless, +you want to check [pyenv-win](https://github.com/pyenv-win/pyenv-win) instead. + +We test, develop, build and publish on Python 3.6.9, and use venvs as preferred: + + git clone git@github.com:asyrjasalo/RESTinstance.git + cd RESTinstance + pyenv install --skip-existing 3.6.9 && pyenv rehash + python3 -m venv .venv/dev + source .venv/dev/bin/activate + pip install -e . + +### Automated venving w/ Nox + +Nox automates handling `.venv/<task>`s for workflows, that on Windows as well: + + pip install --upgrade nox + +The actual tasks are defined in `noxfile.py`, as well as our settings like: +- The default Python interpreter to run all the development tasks is `python3.6` +- We explicitly use [venv module](https://docs.python.org/3/library/venv.html) +now for virtualenving, as we develop on Python >= 3.3 anyway +- Whether a new virtualenv is always recreated when the respective task is run +(which is default for most of our tasks) + +Session is a task, running in the `.venv/<task>`. To list all possible sessions: + + nox -l + +Sessions defined in `RESTinstance/noxfile.py`: + + * test -> Run development tests for the package. + - testenv -> Run development server for acceptance tests. + * atest -> Run acceptance tests for the project. + - docs -> Regenerate documentation for the project. + - black -> Reformat/unify/"blacken" Python source code in-place. + - prospector -> Run various static analysis tools for the package. + - build -> Build sdist and wheel dists. + - release_testpypi -> Publish dist/* to TestPyPI. + - install_testpypi -> Install the latest (pre-)release from TestPyPI. + - release -> Tag, build and publish a new release to PyPI. + - install -> Install the latest release from PyPI. + - clean -> Remove all .venv's, build files and caches in the directory. + +Sessions marked with `*` are selected, sessions marked with `-` are skipped. + +That is, to run both `test`s and `atest`s: + + nox + +Session `nox -s atest` assumes you have started `testapi/` on +[mountebank](https://www.mbtest.org): + + nox -s testenv + +Running the above assumes you have `node` (>= 6) installed in your system. + +After started, you can debug requests and responses by tests in web browser at +[localhost:2525](http://localhost:2525/imposters). + +Both `nox -s test` and `nox -s atest` allow passing arguments to `pytest` +and `robot`, respectively: + + nox -s test -- test/<test_modulename>.py + nox -s atest -- atest/<atest_suitedir>/<atest_suitefile>.robot + +You know, having a virtualenv even for generating `docs/` - why not a bad idea: + + nox -s docs + +### Building and tagging a new version + +Remove all sessions (`.venv/`s) as well as temporary files in your working copy: + + nox -s clean + +Our PyPI distributions are known to work well on Python 3.7 and 2.7 series too: + + nox -s clean build + +We use [zest.releaser](https://github.com/zestsoftware/zest.releaser) for +versioning, tagging and building (universal) `bdist_wheel`s. + +It uses [twine](https://pypi.org/project/twine/) underneath to upload to PyPIs +securely over HTTPS, which can't be done with `python setup.py` commands. + +### Releasing to PyPIs + +This workflow is preferred for distributing a new (pre-)release to TestPyPI: + + nox -s test atest docs clean build release_testpypi install_testpypi + +If that installed well, all will be fine to let the final release to PyPI: + + nox -s release + +To install the latest release from PyPI, and in a dedicated venv of course: + + nox -s install + +### Shell additions + +For intermediate `nox` arguments usage, you'll advance by enabling +[shell completion](https://nox.thea.codes/en/stable/usage.html#shell-completion): + + eval "$(register-python-argcomplete nox)" + +On `zsh`, ensure you have bash compatibility enabled in `.zshrc` or similar: + + autoload -U bashcompinit + bashcompinit + +These completions likely do not work on vanilla PowerShell, but can be used on +[Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install-win10). + +### Unified Python editor/IDE linters + +Catching errors already write-time, regardless of the editor, is advantaged by +[Palantir's Python Language Server](https://github.com/palantir/python-language-server): + + python3 -m venv .venv/dev + source .venv/dev/bin/activate + pip install --upgrade python-language-server[all] + +Installing the all bundle, and the LSP plugin for your editor, enables to run +useful linters real-time, like: + +- Either `autopep8` or `black` (preferred) for automated code formatting +- `isort` for sorting code import statements +- McCabe for code complexity checking +- `mypy` for static type checking on Python 3 +- `pycodestyle` for coding style checking +- `pyflakes` for detecting various coding errors + +Remember to (auto-)start the language server on background via your editor. + +### pre-commit hooks + +We want our static analysis checks ran before code even ends up in a commit. + +Thus both `nox` and `nox -s test` commands bootstrap +[pre-commit](https://pre-commit.com/) hooks in your git working copy. + +The actual hooks are configured in `.pre-commit-commit.yaml`. + +### Ideas + +- export `mb` recorded responses to CI (pre-commit hook: `nox -s save_testenv`) +- change `nox -s testenv` to load the saved testenv -> rid of `--allowInjection` +- add CI (GitHub Actions? GitLab?) +- add Python types to pass `prospector --with-tool mypy` +- enable pre-commit hook for prospector + + + +## Credits + +RESTinstance is under +[Apache License 2.0](https://github.com/asyrjasalo/RESTinstance/blob/master/LICENSE) +and was originally written by [Anssi Syrjäsalo](https://github.com/asyrjasalo). + +It was first presented at the first [RoboCon](https://robocon.io), 2018. + +Contributors: + +- [jjwong](https://github.com/jjwong) for helping with keyword +documentation and examples (also check +[RESTinstance_starter_project](https://github.com/jjwong/RESTinstance_starter_project)) +- [Przemysław "sqilz" Hendel](https://github.com/sqilz) for using and +testing RESTinstance in early phase (also check +[RESTinstance-wrapper](https://github.com/sqilz/RESTinstance-wrapper)) +- [Vinh "vinhntb" Nguyen](https://github.com/vinhntb), +[#52](https://github.com/asyrjasalo/RESTinstance/pull/52). +- [Stavros "stdedos" Ntentos](https://github.com/stdedos), +[#75](https://github.com/asyrjasalo/RESTinstance/pull/75). +- [Nicholas "bollwyvl" Bollweg](https://github.com/bollwyvl), +[#84](https://github.com/asyrjasalo/RESTinstance/pull/84). +- [Trey Turner](https://github.com/treyturner), [#86](https://github.com/asyrjasalo/RESTinstance/pull/86) + +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, in terminal <span class="title-ref">Output</span> +- [requests](https://github.com/requests/requests), by Kenneth Reitz +et al., for making HTTP requests + +See +[requirements.txt](https://github.com/asyrjasalo/RESTinstance/blob/master/requirements.txt) +for all the direct run time dependencies. + +REST your mind, OSS got your back. + + + + +%package help +Summary: Development documents and examples for RESTinstance +Provides: python3-RESTinstance-doc +%description help +# RESTinstance + +[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 + +On 3.6, 3.7 you can install and upgrade +[from PyPi](https://pypi.org/project/RESTinstance): + + python3 -m venv venv + source venv/bin/activate + pip install --upgrade RESTinstance + +On 2.7 series the package works as well, but using 2.7 is +[not preferred 2020 onwards](https://pythonclock.org/): + + pip install --user --upgrade virtualenv + virtualenv venv + source venv/bin/activate + pip install --upgrade RESTinstance + +These also install [Robot Framework](https://pypi.org/project/robotframework) +if you do not have it already. + + + +## Usage + +There is a +[step-by-step tutorial](https://github.com/asyrjasalo/RESTinstance/blob/master/examples) +in the making, best accompanied with +[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 + +Bug reports and feature requests are tracked in +[GitHub](https://github.com/asyrjasalo/RESTinstance/issues). +We do respect pull request(er)s. + +### Local development + +The logic is detaching the enving from system level (dependencies) as following: +1. We use [pyenv](https://github.com/pyenv/pyenv) to manage n Pythons user-wide. +2. With Pyenv installed Pythons, we never mess with the system's default Python. +3. We ended up to [Nox](https://nox.thea.codes/en/stable/) after evaluating +Bash scripts, `make`, `invoke` and `tox` to achieve automated virtualenving. + +To understand the first two of the practices, these are worth reading: +- [Real Python's intro to pyenv](https://realpython.com/intro-to-pyenv) +- [Real Python's virtualenvs primer](https://realpython.com/python-virtual-environments-a-primer/) +- [virtualenv compatibility with the stdlib venv module](https://virtualenv.pypa.io/en/latest/reference/#compatibility-with-the-stdlib-venv-module) + +Third, unlike Tox, Nox uses Python file (`noxfile.py`) for configuration, yet: +- Supports multiple Python versions, each session is ran on some `pythonX.X`. +- A session is a single virtualenv which is stored in `.venv/<session_name>`. +- Every `nox` recreates session, thus virtualenv, unless `reuse_venv=True`. + +### Python versioning w/ pyenv + +The pyenv setup works on OS X and on the common Linux distros out of the box: + + curl https://pyenv.run | bash + export PATH="$HOME/.pyenv/bin:$PATH" + eval "$(pyenv init -)" + +The first script installs it user-wide, thus it never requires `sudo` rights. + +If you are on Windows, using pyenv might or might not be an option. Regardless, +you want to check [pyenv-win](https://github.com/pyenv-win/pyenv-win) instead. + +We test, develop, build and publish on Python 3.6.9, and use venvs as preferred: + + git clone git@github.com:asyrjasalo/RESTinstance.git + cd RESTinstance + pyenv install --skip-existing 3.6.9 && pyenv rehash + python3 -m venv .venv/dev + source .venv/dev/bin/activate + pip install -e . + +### Automated venving w/ Nox + +Nox automates handling `.venv/<task>`s for workflows, that on Windows as well: + + pip install --upgrade nox + +The actual tasks are defined in `noxfile.py`, as well as our settings like: +- The default Python interpreter to run all the development tasks is `python3.6` +- We explicitly use [venv module](https://docs.python.org/3/library/venv.html) +now for virtualenving, as we develop on Python >= 3.3 anyway +- Whether a new virtualenv is always recreated when the respective task is run +(which is default for most of our tasks) + +Session is a task, running in the `.venv/<task>`. To list all possible sessions: + + nox -l + +Sessions defined in `RESTinstance/noxfile.py`: + + * test -> Run development tests for the package. + - testenv -> Run development server for acceptance tests. + * atest -> Run acceptance tests for the project. + - docs -> Regenerate documentation for the project. + - black -> Reformat/unify/"blacken" Python source code in-place. + - prospector -> Run various static analysis tools for the package. + - build -> Build sdist and wheel dists. + - release_testpypi -> Publish dist/* to TestPyPI. + - install_testpypi -> Install the latest (pre-)release from TestPyPI. + - release -> Tag, build and publish a new release to PyPI. + - install -> Install the latest release from PyPI. + - clean -> Remove all .venv's, build files and caches in the directory. + +Sessions marked with `*` are selected, sessions marked with `-` are skipped. + +That is, to run both `test`s and `atest`s: + + nox + +Session `nox -s atest` assumes you have started `testapi/` on +[mountebank](https://www.mbtest.org): + + nox -s testenv + +Running the above assumes you have `node` (>= 6) installed in your system. + +After started, you can debug requests and responses by tests in web browser at +[localhost:2525](http://localhost:2525/imposters). + +Both `nox -s test` and `nox -s atest` allow passing arguments to `pytest` +and `robot`, respectively: + + nox -s test -- test/<test_modulename>.py + nox -s atest -- atest/<atest_suitedir>/<atest_suitefile>.robot + +You know, having a virtualenv even for generating `docs/` - why not a bad idea: + + nox -s docs + +### Building and tagging a new version + +Remove all sessions (`.venv/`s) as well as temporary files in your working copy: + + nox -s clean + +Our PyPI distributions are known to work well on Python 3.7 and 2.7 series too: + + nox -s clean build + +We use [zest.releaser](https://github.com/zestsoftware/zest.releaser) for +versioning, tagging and building (universal) `bdist_wheel`s. + +It uses [twine](https://pypi.org/project/twine/) underneath to upload to PyPIs +securely over HTTPS, which can't be done with `python setup.py` commands. + +### Releasing to PyPIs + +This workflow is preferred for distributing a new (pre-)release to TestPyPI: + + nox -s test atest docs clean build release_testpypi install_testpypi + +If that installed well, all will be fine to let the final release to PyPI: + + nox -s release + +To install the latest release from PyPI, and in a dedicated venv of course: + + nox -s install + +### Shell additions + +For intermediate `nox` arguments usage, you'll advance by enabling +[shell completion](https://nox.thea.codes/en/stable/usage.html#shell-completion): + + eval "$(register-python-argcomplete nox)" + +On `zsh`, ensure you have bash compatibility enabled in `.zshrc` or similar: + + autoload -U bashcompinit + bashcompinit + +These completions likely do not work on vanilla PowerShell, but can be used on +[Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install-win10). + +### Unified Python editor/IDE linters + +Catching errors already write-time, regardless of the editor, is advantaged by +[Palantir's Python Language Server](https://github.com/palantir/python-language-server): + + python3 -m venv .venv/dev + source .venv/dev/bin/activate + pip install --upgrade python-language-server[all] + +Installing the all bundle, and the LSP plugin for your editor, enables to run +useful linters real-time, like: + +- Either `autopep8` or `black` (preferred) for automated code formatting +- `isort` for sorting code import statements +- McCabe for code complexity checking +- `mypy` for static type checking on Python 3 +- `pycodestyle` for coding style checking +- `pyflakes` for detecting various coding errors + +Remember to (auto-)start the language server on background via your editor. + +### pre-commit hooks + +We want our static analysis checks ran before code even ends up in a commit. + +Thus both `nox` and `nox -s test` commands bootstrap +[pre-commit](https://pre-commit.com/) hooks in your git working copy. + +The actual hooks are configured in `.pre-commit-commit.yaml`. + +### Ideas + +- export `mb` recorded responses to CI (pre-commit hook: `nox -s save_testenv`) +- change `nox -s testenv` to load the saved testenv -> rid of `--allowInjection` +- add CI (GitHub Actions? GitLab?) +- add Python types to pass `prospector --with-tool mypy` +- enable pre-commit hook for prospector + + + +## Credits + +RESTinstance is under +[Apache License 2.0](https://github.com/asyrjasalo/RESTinstance/blob/master/LICENSE) +and was originally written by [Anssi Syrjäsalo](https://github.com/asyrjasalo). + +It was first presented at the first [RoboCon](https://robocon.io), 2018. + +Contributors: + +- [jjwong](https://github.com/jjwong) for helping with keyword +documentation and examples (also check +[RESTinstance_starter_project](https://github.com/jjwong/RESTinstance_starter_project)) +- [Przemysław "sqilz" Hendel](https://github.com/sqilz) for using and +testing RESTinstance in early phase (also check +[RESTinstance-wrapper](https://github.com/sqilz/RESTinstance-wrapper)) +- [Vinh "vinhntb" Nguyen](https://github.com/vinhntb), +[#52](https://github.com/asyrjasalo/RESTinstance/pull/52). +- [Stavros "stdedos" Ntentos](https://github.com/stdedos), +[#75](https://github.com/asyrjasalo/RESTinstance/pull/75). +- [Nicholas "bollwyvl" Bollweg](https://github.com/bollwyvl), +[#84](https://github.com/asyrjasalo/RESTinstance/pull/84). +- [Trey Turner](https://github.com/treyturner), [#86](https://github.com/asyrjasalo/RESTinstance/pull/86) + +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, in terminal <span class="title-ref">Output</span> +- [requests](https://github.com/requests/requests), by Kenneth Reitz +et al., for making HTTP requests + +See +[requirements.txt](https://github.com/asyrjasalo/RESTinstance/blob/master/requirements.txt) +for all the direct run time dependencies. + +REST your mind, OSS got your back. + + + + +%prep +%autosetup -n RESTinstance-1.3.0 + +%build +%py3_build + +%install +%py3_install +install -d -m755 %{buildroot}/%{_pkgdocdir} +if [ -d doc ]; then cp -arf doc %{buildroot}/%{_pkgdocdir}; fi +if [ -d docs ]; then cp -arf docs %{buildroot}/%{_pkgdocdir}; fi +if [ -d example ]; then cp -arf example %{buildroot}/%{_pkgdocdir}; fi +if [ -d examples ]; then cp -arf examples %{buildroot}/%{_pkgdocdir}; fi +pushd %{buildroot} +if [ -d usr/lib ]; then + find usr/lib -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/lib64 ]; then + find usr/lib64 -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/bin ]; then + find usr/bin -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/sbin ]; then + find usr/sbin -type f -printf "/%h/%f\n" >> filelist.lst +fi +touch doclist.lst +if [ -d usr/share/man ]; then + find usr/share/man -type f -printf "/%h/%f.gz\n" >> doclist.lst +fi +popd +mv %{buildroot}/filelist.lst . +mv %{buildroot}/doclist.lst . + +%files -n python3-RESTinstance -f filelist.lst +%dir %{python3_sitelib}/* + +%files help -f doclist.lst +%{_docdir}/* + +%changelog +* Tue Apr 11 2023 Python_Bot <Python_Bot@openeuler.org> - 1.3.0-1 +- Package Spec generated |