diff --git a/README.md b/README.md index 022c7ee..e1525b4 100644 --- a/README.md +++ b/README.md @@ -123,7 +123,7 @@ Boom. Install the latest release: - $ pipenv install responder + $ pipenv install responder --pre ✨🍰✨ diff --git a/docs/source/index.rst b/docs/source/index.rst index 2ebba01..18c03fc 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -105,6 +105,7 @@ User Guides quickstart tour deployment + testing api @@ -113,7 +114,7 @@ Installing Responder .. code-block:: shell - $ pipenv install responder + $ pipenv install responder --pre ✨🍰✨ Only **Python 3.6+** is supported. diff --git a/docs/source/testing.rst b/docs/source/testing.rst new file mode 100644 index 0000000..d860b3e --- /dev/null +++ b/docs/source/testing.rst @@ -0,0 +1,79 @@ +Building and Testing with Responder +=================================== + +Responder comes with a first-class, well supported test client for your ASGI web services: **Requests**. + +Here, we'll go over the basics of setting up a proper Python package and adding testing to it. + +The Basics +---------- + +Your repository should look like this:: + + Pipfile Pipfile.lock api.py test_api.py + +``$ cat api.py``:: + + import responder + + api = responder.API() + + @api.route("/") + def hello_world(req, resp): + resp.text = "hello, world!" + + if __name__ == "__main__": + api.run() + + +``$ cat Pipfile``:: + + [[source]] + url = "https://pypi.org/simple" + verify_ssl = true + name = "pypi" + + [packages] + responder = "*" + + [dev-packages] + pytest = "*" + + [requires] + python_version = "3.7" + + [pipenv] + allow_prereleases = true + +Writing Tests +============= + +``$ cat test_api.py``:: + + import pytest + import api as service + + @pytest.fixture + def api(): + return service.api + + + def test_hello_world(api): + r = api.requests.get("/") + assert r.text = "hello, world!" + +``$ pytest``:: + + ... + ========================== 1 passed in 0.10 seconds ========================== + + +(Optional) Proper Python Package +-------------------------------- + +Optionally, you can not rely on relative imports, and instead install your api as a proper package. This requires: + +1. A `proper setup.py `_ file. +2. ``$ pipenv install -e . --dev`` + +This will ensure that your application gets installed in every developer's environment, using Pipenv.