docs: Cleanup documentation

CONTRIBUTING.rst

@@ -1,9 +1,9 @@
 Contributing to Schemathesis
 ============================
 
-Welcome! We are very happy that you're reading this!
+Welcome! We are delighted that you're reading this!
 
-Your feedback and your experience are important for the project :)
+Your feedback and your experience are essential for the project :)
 
 .. contents::
    :depth: 2
@@ -16,9 +16,9 @@ If you'd like to suggest a feature, feel free to `submit an issue <https://githu
 and:
 
 * Write a simple and descriptive title to identify your suggestion.
-* Provide as many details as possible, explain your context and how the feature should work.
+* Provide as many details as possible, explain your context, and how the feature should work.
 * Explain why this improvement would be useful.
-* Keep the scope narrow. This will make it easier to implement.
+* Keep the scope narrow. It will make it easier to implement.
 
 Report bugs
 -----------
@@ -29,12 +29,31 @@ If you are reporting a bug, please:
 
 * Write a simple and descriptive title to identify the problem.
 * Describe the exact steps which reproduce the problem in as many details as possible.
-* Describe the behavior you observed after following the steps and point out what exactly is the problem with that behavior.
+* Describe the behavior you observed after following the steps and point out the problem with that behavior.
 * Explain which behavior you expected to see instead and why.
 * Include Python / Schemathesis versions.
 
 It would be awesome if you can submit a failing test that demonstrates the problem.
 
+Submitting Pull Requests
+------------------------
+
+#. Fork the repository.
+#. Enable and install `pre-commit <https://pre-commit.com>`_ to ensure style-guides and code checks are followed.
+#. Target the ``master`` branch.
+#. Follow **PEP-8** for naming and `black <https://github.com/psf/black>`_ for formatting.
+#. Tests are run using ``tox``::
+
+    tox -e pylint,mypy,py37
+
+   The test environments above are usually enough to cover most cases locally.
+
+#. Write an entry to `changelog.rst <https://github.com/schemathesis/schemathesis/blob/master/docs/changelog.rst>`_
+#. Format your commit message according to the Conventional Commits `specification <https://www.conventionalcommits.org/en/>`_
+
+For each pull request, we aim to review it as soon as possible.
+If you wait a few days without a reply, please feel free to ping the thread by adding a new comment.
+
 Using a local test server
 -------------------------
 
@@ -142,26 +161,10 @@ Then you could use CLI against this server:
 
     ================================================== 3 passed in 1.77s ==================================================
 
-Submitting Pull Requests
-------------------------
-
-#. Fork the repository.
-#. Enable and install `pre-commit <https://pre-commit.com>`_ to ensure style-guides and code checks are followed.
-#. Target the ``master`` branch.
-#. Follow **PEP-8** for naming and `black <https://github.com/psf/black>`_ for formatting.
-#. Tests are run using ``tox``::
-
-    tox -e pylint,mypy,py37
-
-   The test environments above are usually enough to cover most cases locally.
-
-#. Write an entry to `changelog.rst <https://github.com/schemathesis/schemathesis/blob/master/docs/changelog.rst>`_
-#. Format your commit message according to the Conventional Commits `specification <https://www.conventionalcommits.org/en/>`_
-
-For each pull request, we aim to review it as soon as possible.
-If you wait a few days without a reply, please feel free to ping the thread by adding a new comment.
+Maintainers
+-----------
 
-At present the core developers are:
+At present, the core developers are:
 
 - Dmitry Dygalo (`@Stranger6667`_)
 

README.rst

@@ -7,10 +7,10 @@ Schemathesis is a modern API testing tool for web applications built with Open A
 
 It reads the application schema and generates test cases, which will ensure that your application is compliant with its schema.
 
-Simple to use and yet powerful to uncover hard-to-find errors thanks to the property-based testing approach backed by state-of-the-art `Hypothesis <http://hypothesis.works/>`_ library.
-
 The application under test could be written in any language; the only thing you need is a valid API schema in a supported format.
 
+Simple to use and yet powerful to uncover hard-to-find errors thanks to the property-based testing approach backed by state-of-the-art `Hypothesis <http://hypothesis.works/>`_ library.
+
 Features
 --------
 
@@ -54,10 +54,9 @@ Or in your Python tests:
 
     @schema.parametrize()
     def test_api(case):
-        response = case.call()
-        case.validate_response(response)
+        case.call_and_validate()
 
-CLI is pretty simple to use and requires no coding; the in-code approach gives more flexibility.
+CLI is simple to use and requires no coding; the in-code approach gives more flexibility.
 
 Contributing
 ------------
@@ -72,8 +71,8 @@ It will take 5 minutes. The results are anonymous.
 
 **Survey**: https://forms.gle/dv4s5SXAYWzvuwFWA
 
-Support
--------
+Support this project
+--------------------
 
 Hi, my name is Dmitry! I started this project during my work at `Kiwi.com <https://kiwi.com/>`_. I am grateful to them for all the support they
 provided to this project during its early days and for the opportunity to evolve Schemathesis independently.

docs/cli.rst

@@ -63,7 +63,21 @@ For example, the following command will select all endpoints which paths start w
 
     $ schemathesis run -E ^/api/users http://api.com/swagger.json
 
-How responses are checked?
+Tests configuration
+-------------------
+
+Schemathesis is built on top of the `Hypothesis <http://hypothesis.works/>`_ library and allows you to configure testing process in the same way.
+
+We support all configuration options accepted by the ``hypothesis.settings`` decorator.
+All of them are prefixed with ``--hypothesis-`` and underscores are replaced with dashes, for example:
+
+- ``--hypothesis-max-examples=1000``. Generate up to 1000 test cases per endpoint;
+- ``--hypothesis-phases=explicit``. Run only examples, specified explicitly in the API schema;
+- ``--hypothesis-suppress-health-check=too_slow``. Disables the ``too_slow`` health check and makes Schemathesis continue testing even if it is considered too slow.
+
+See the whole list of available options via the ``schemathesis run --help`` command and in the `Hypothesis documentation <https://hypothesis.readthedocs.io/en/latest/settings.html#available-settings>`_.
+
+How are responses checked?
 --------------------------
 
 For each API response received during the test, Schemathesis runs several checks to verify response conformance. By default,
@@ -105,20 +119,6 @@ To make Schemathesis perform all built-in checks use ``--check all`` CLI option:
 
     ======================= 3 passed in 1.69s =======================
 
-Tests configuration
--------------------
-
-Schemathesis is built on top of the `Hypothesis <http://hypothesis.works/>`_ library and allows you to configure testing process in the same way.
-
-We support all configuration options accepted by the ``hypothesis.settings`` decorator.
-All of them are prefixed with ``--hypothesis-`` and underscores are replaced with dashes, for example:
-
-- ``--hypothesis-max-examples=1000``. Generate up to 1000 test cases per endpoint;
-- ``--hypothesis-phases=explicit``. Run only examples, specified explicitly in the API schema;
-- ``--hypothesis-suppress-health-check=too_slow``. Disables the ``too_slow`` health check and makes Schemathesis continue testing even if it is considered too slow.
-
-See the whole list of available options via the ``schemathesis run --help`` command and in the `Hypothesis documentation <https://hypothesis.readthedocs.io/en/latest/settings.html#available-settings>`_.
-
 API authorization
 -----------------
 

docs/graphql.rst

@@ -18,8 +18,7 @@ Usage
     @schema.parametrize()
     @settings(deadline=None)
     def test(case):
-        response = case.call()
-        case.validate_response(response)
+        case.call_and_validate()
 
 This test will load GraphQL schema from ``https://bahnql.herokuapp.com/graphql``, generate queries for it, send them to the server, and verify responses.
 

docs/index.rst

@@ -5,10 +5,10 @@ Schemathesis is a modern API testing tool for web applications built with Open A
 
 It reads the application schema and generates test cases, which will ensure that your application is compliant with its schema.
 
-Simple to use and yet powerful to uncover hard-to-find errors thanks to the property-based testing approach backed by state-of-the-art `Hypothesis <http://hypothesis.works/>`_ library.
-
 The application under test could be written in any language; the only thing you need is a valid API schema in a supported format.
 
+Simple to use and yet powerful to uncover hard-to-find errors thanks to the property-based testing approach backed by state-of-the-art `Hypothesis <http://hypothesis.works/>`_ library.
+
 You can use Schemathesis in the command line:
 
 .. code:: bash
@@ -25,8 +25,7 @@ Or in your Python tests:
 
     @schema.parametrize()
     def test_api(case):
-        response = case.call()
-        case.validate_response(response)
+        case.call_and_validate()
 
 Features
 --------

docs/python.rst

@@ -17,8 +17,7 @@ The following test will load the API schema from ``http://0.0.0.0:8080/swagger.j
 
     @schema.parametrize()
     def test_api(case):
-        response = case.call()
-        case.validate_response(response)
+        case.call_and_validate()
 
 Each test set includes up to 100 test cases by default, depending on the endpoint definition.
 
@@ -64,8 +63,7 @@ For example, the following test selects all endpoints which paths start with ``/
 
     @schema.parametrize(endpoint="^/api/users")
     def test_api(case):
-        response = case.call()
-        case.validate_response(response)
+        case.call_and_validate()
 
 Tests configuration
 -------------------
@@ -117,8 +115,8 @@ When the received response is validated, Schemathesis runs the following checks:
 
 Validation happens in the ``case.validate_response`` function, but you can add your code to verify the response conformance as you do in regular Python tests.
 
-ASGI/WSGI applications support
-------------------------------
+ASGI / WSGI support
+-------------------
 
 Schemathesis supports making calls to ASGI and WSGI-compliant applications instead of real network calls;
 in this case, the test execution will go much faster.
@@ -161,8 +159,7 @@ You only need to specify strategies for ``hypothesis.given``:
 
         @given(case=new_pet_strategy)
         def test_pets(self, case):
-            response = case.call()
-            case.validate_response(response)
+            case.call_and_validate()
 
 Anatomy of a test
 -----------------
@@ -178,14 +175,13 @@ seamlessly combines your API schema with ``pytest``-style parametrization and pr
 
     @schema.parametrize()
     def test_api(case):
-        response = case.call()
-        case.validate_response(response)
+        case.call_and_validate()
 
 Such test consists of four main parts:
 
 1. Schema preparation; In this case, the schema is loaded via the ``from_uri`` function.
 2. Test parametrization; ``@schema.parametrize()`` generates separate tests for all endpoint/method combinations available in the schema.
-3. A network call to the running application; ``case.call`` does it.
+3. A network call to the running application; ``case.call_and_validate()`` does it.
 4. Verifying a property you'd like to test; In this example, we run all built-in checks.
 
 Each test function where you use ``schema.parametrize`` should have the ``case`` fixture, representing a single test case.

docs/stateful.rst

@@ -88,14 +88,14 @@ Python tests:
 
     @schema.parametrize(stateful=Stateful.links)
     def test_api(case):
-        response = case.call()
+        case.call_and_validate()
         ...
 
 Each additional test will be indented and prefixed with ``->`` in the CLI output.
 You can specify recursive links if you want. The default recursion depth limit is **5** and can be changed with the
 ``--stateful-recursion-limit=<N>`` CLI option or with the ``stateful_recursion_limit=<N>`` argument to ``parametrize``.
 
-**NOTE**. If you use stateful testing in Python tests, make sure you use the ``case.call`` method that automatically stores the response for further usage.
+**NOTE**. If you use stateful testing in Python tests, make sure you use the ``case.call_and_validate`` or ``case.call`` methods that automatically store the response for further usage.
 Alternatively, you could use ``case.store_response`` and store the received response by hand:
 
 .. code:: python