diff --git a/AUTHORS b/AUTHORS index 862378be9f5..55772997833 100644 --- a/AUTHORS +++ b/AUTHORS @@ -38,6 +38,7 @@ Christian Boelsen Christian Theunert Christian Tismer Christopher Gilling +Cyrus Maden Daniel Grana Daniel Hahler Daniel Nuri diff --git a/changelog/3131.doc b/changelog/3131.doc new file mode 100644 index 00000000000..28e61c1d8bf --- /dev/null +++ b/changelog/3131.doc @@ -0,0 +1 @@ +Improve readability (wording, grammar) of Getting Started guide diff --git a/doc/en/getting-started.rst b/doc/en/getting-started.rst index 64b0108262d..3c6391c6a45 100644 --- a/doc/en/getting-started.rst +++ b/doc/en/getting-started.rst @@ -7,32 +7,34 @@ Installation and Getting Started **PyPI package name**: `pytest `_ -**dependencies**: `py `_, +**Dependencies**: `py `_, `colorama (Windows) `_, -**documentation as PDF**: `download latest `_ +**Documentation as PDF**: `download latest `_ + +``pytest`` is a framework that makes building simple and scalable tests easy. Tests are expressive and readable—no boilerplate code required. Get started in minutes with a small unit test or complex functional test for your application or library. .. _`getstarted`: -.. _installation: +.. _`installation`: -Installation +Install ``pytest`` ---------------------------------------- -Installation:: +1. Run the following command in your command line:: pip install -U pytest -To check your installation has installed the correct version:: +2. Check that you installed the correct version:: $ pytest --version This is pytest version 3.x.y, imported from $PYTHON_PREFIX/lib/python3.5/site-packages/pytest.py .. _`simpletest`: -Our first test run +Create your first test ---------------------------------------------------------- -Let's create a first test file with a simple test function:: +Create a simple test function with just four lines of code:: # content of test_sample.py def func(x): @@ -41,7 +43,7 @@ Let's create a first test file with a simple test function:: def test_answer(): assert func(3) == 5 -That's it. You can execute the test function now:: +That’s it. You can now execute the test function:: $ pytest =========================== test session starts ============================ @@ -62,30 +64,22 @@ That's it. You can execute the test function now:: test_sample.py:5: AssertionError ========================= 1 failed in 0.12 seconds ========================= -We got a failure report because our little ``func(3)`` call did not return ``5``. +This test returns a failure report because ``func(3)`` does not return ``5``. .. note:: - You can simply use the ``assert`` statement for asserting test - expectations. pytest's :ref:`assert introspection` will intelligently - report intermediate values of the assert expression freeing - you from the need to learn the many names of `JUnit legacy methods`_. - -.. _`JUnit legacy methods`: http://docs.python.org/library/unittest.html#test-cases - -.. _`assert statement`: http://docs.python.org/reference/simple_stmts.html#the-assert-statement + You can use the ``assert`` statement to verify test expectations. pytest’s `Advanced assertion introspection `_ will intelligently report intermediate values of the assert expression so you can avoid the many names `of JUnit legacy methods `_. -Running multiple tests +Run multiple tests ---------------------------------------------------------- -``pytest`` will run all files in the current directory and its subdirectories of the form test_*.py or \*_test.py. More generally, it follows :ref:`standard test discovery rules `. +``pytest`` will run all files of the form test_*.py or \*_test.py in the current directory and its subdirectories. More generally, it follows :ref:`standard test discovery rules `. -Asserting that a certain exception is raised +Assert that a certain exception is raised -------------------------------------------------------------- -If you want to assert that some code raises an exception you can -use the ``raises`` helper:: +Use the ``raises`` helper to assert that some code raises an exception:: # content of test_sysexit.py import pytest @@ -96,18 +90,16 @@ use the ``raises`` helper:: with pytest.raises(SystemExit): f() -Running it with, this time in "quiet" reporting mode:: +Execute the test function with “quiet” reporting mode:: $ pytest -q test_sysexit.py . [100%] 1 passed in 0.12 seconds -Grouping multiple tests in a class +Group multiple tests in a class -------------------------------------------------------------- -Once you start to have more than a few tests it often makes sense -to group tests logically, in classes and modules. Let's write a class -containing two tests:: +Once you develop multiple tests, you may want to group them into a class. pytest makes it easy to create a class containing more than one test:: # content of test_class.py class TestClass(object): @@ -119,9 +111,7 @@ containing two tests:: x = "hello" assert hasattr(x, 'check') -The two tests are found because of the standard :ref:`test discovery`. -There is no need to subclass anything. We can simply -run the module by passing its filename:: +``pytest`` discovers all tests following its :ref:`Conventions for Python test discovery `, so it finds both ``test_`` prefixed functions. There is no need to subclass anything. We can simply run the module by passing its filename:: $ pytest -q test_class.py .F [100%] @@ -139,26 +129,19 @@ run the module by passing its filename:: test_class.py:8: AssertionError 1 failed, 1 passed in 0.12 seconds -The first test passed, the second failed. Again we can easily see -the intermediate values used in the assertion, helping us to -understand the reason for the failure. +The first test passed and the second failed. You can easily see the intermediate values in the assertion to help you understand the reason for the failure. -Going functional: requesting a unique temporary directory +Request a unique temporary directory for functional tests -------------------------------------------------------------- -For functional tests one often needs to create some files -and pass them to application objects. pytest provides -:ref:`builtinfixtures` which allow to request arbitrary -resources, for example a unique temporary directory:: +``pytest`` provides `Builtin fixtures/function arguments `_ to request arbitrary resources, like a unique temporary directory:: # content of test_tmpdir.py def test_needsfiles(tmpdir): print (tmpdir) assert 0 -We list the name ``tmpdir`` in the test function signature and -``pytest`` will lookup and call a fixture factory to create the resource -before performing the test function call. Let's just run it:: +List the name ``tmpdir`` in the test function signature and ``pytest`` will lookup and call a fixture factory to create the resource before performing the test function call. Before the test runs, ``pytest`` creates a unique-per-test-invocation temporary directory:: $ pytest -q test_tmpdir.py F [100%] @@ -177,22 +160,21 @@ before performing the test function call. Let's just run it:: PYTEST_TMPDIR/test_needsfiles0 1 failed in 0.12 seconds -Before the test runs, a unique-per-test-invocation temporary directory -was created. More info at :ref:`tmpdir handling`. +More info on tmpdir handeling is available at `Temporary directories and files `_. -You can find out what kind of builtin :ref:`fixtures` exist by typing:: +Find out what kind of builtin ```pytest`` fixtures `_ exist with the command:: pytest --fixtures # shows builtin and custom fixtures -Where to go next +Continue reading ------------------------------------- -Here are a few suggestions where to go next: +Check out additional pytest resources to help you customize tests for your unique workflow: -* :ref:`cmdline` for command line invocation examples -* :ref:`good practices ` for virtualenv, test layout -* :ref:`existingtestsuite` for working with pre-existing tests -* :ref:`fixtures` for providing a functional baseline to your tests -* :ref:`plugins` managing and writing plugins +* ":ref:`cmdline`" for command line invocation examples +* ":ref:`goodpractices`" for virtualenv and test layouts +* ":ref:`existingtestsuite`" for working with pre-existing tests +* ":ref:`fixtures`" for providing a functional baseline to your tests +* ":ref:`plugins`" for managing and writing plugins .. include:: links.inc