From 1f4831a23fdfab060006f65bb4fa891167374f2f Mon Sep 17 00:00:00 2001 From: Cyrus Maden Date: Mon, 15 Jan 2018 12:28:21 -0800 Subject: [PATCH 1/9] Update getting-started.rst --- doc/en/getting-started.rst | 86 ++++++++++++++++---------------------- 1 file changed, 36 insertions(+), 50 deletions(-) diff --git a/doc/en/getting-started.rst b/doc/en/getting-started.rst index 64b0108262d..d4847d59b38 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: +.. _`installpytest`: -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`: +.. _`createyourfirsttest`: -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,26 @@ 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`_. + You can use the ``assert`` statement to verify test expectations. pytest’s :ref:`Advanced assertion introspection` will intelligently report intermediate values of the assert expression so you can avoid 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 +.. _`Advanced assertion introspection`: http://docs.python.org/reference/simple_stmts.html#the-assert-statement -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 +94,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 +115,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 +133,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 +164,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 From f555a3a76cc205b0f0d2b253d0146290e7ca34cf Mon Sep 17 00:00:00 2001 From: Cyrus Maden Date: Mon, 15 Jan 2018 13:27:10 -0800 Subject: [PATCH 2/9] Update getting started guide Proofread; added intro paragraph under first header to orient new users; fixed grammar errors (switched to active voice, actionable directions, etc) to improve readability --- .DS_Store | Bin 0 -> 6148 bytes doc/.DS_Store | Bin 0 -> 6148 bytes doc/en/.DS_Store | Bin 0 -> 6148 bytes doc/en/getting-started.rst | 14 +++++--------- 4 files changed, 5 insertions(+), 9 deletions(-) create mode 100644 .DS_Store create mode 100644 doc/.DS_Store create mode 100644 doc/en/.DS_Store diff --git a/.DS_Store b/.DS_Store new file mode 100644 index 0000000000000000000000000000000000000000..7cbe275046a42350e05301fa3e51caa9dcc81710 GIT binary patch literal 6148 zcmeH~Jr2S!425ml0g0s}V-^m;4I%_5-~tFbB6UFQIXcfj3xyd~=vlJA*s0a_4NWZ~ zdU%d|kwHY(aHH%j%uJDYGRh>k@o~Ffr|E7bw^h;#@Ihw#xlK?3DnJFO02QDD3sN8t z^7Upx&%{Te0#slb3fT9dz>PK8g8u11@DTv)QFg=HX9=)a0j$XuLtMpWxr-|5*!DDnJGPOabkW z=i>n{m1pb6>skGhRa-YW=$9kB{RAMfqj(EA!;KrJ4LH~3h_y_>bP3Z5S>vG!N$@uSMUZw^aLJ2(QSkU3$fqIb9pr1d;e&iX;6Vd)od{|=!lohtBGA;&_%QP(7ai*Ls7pS=NC^Gt$`e=02O#vU>M7p)&Dj8 zP5=K);))7Tfxl8fN2|?hi6>=k?LE$FZGrFLmUDxfVeS+RUXFoYjlb| WP3!`lj=0l-{24G^XjI_a3fut+K^1ra literal 0 HcmV?d00001 diff --git a/doc/en/getting-started.rst b/doc/en/getting-started.rst index d4847d59b38..3c6391c6a45 100644 --- a/doc/en/getting-started.rst +++ b/doc/en/getting-started.rst @@ -15,7 +15,7 @@ Installation and Getting Started ``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`: -.. _`installpytest`: +.. _`installation`: Install ``pytest`` ---------------------------------------- @@ -29,7 +29,7 @@ Install ``pytest`` $ pytest --version This is pytest version 3.x.y, imported from $PYTHON_PREFIX/lib/python3.5/site-packages/pytest.py -.. _`createyourfirsttest`: +.. _`simpletest`: Create your first test ---------------------------------------------------------- @@ -68,11 +68,7 @@ This test returns a failure report because ``func(3)`` does not return ``5``. .. note:: - You can use the ``assert`` statement to verify test expectations. pytest’s :ref:`Advanced assertion introspection` will intelligently report intermediate values of the assert expression so you can avoid the many names `of JUnit legacy methods`_. - -.. _`JUnit legacy methods`: http://docs.python.org/library/unittest.html#test-cases - -.. _`Advanced assertion introspection`: 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 `_. Run multiple tests ---------------------------------------------------------- @@ -115,7 +111,7 @@ Once you develop multiple tests, you may want to group them into a class. pytest x = "hello" assert hasattr(x, 'check') -``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`` 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%] @@ -138,7 +134,7 @@ The first test passed and the second failed. You can easily see the intermediate Request a unique temporary directory for functional tests -------------------------------------------------------------- -``pytest`` provides `Builtin fixtures/function arguments `_ to request arbitrary resources, like 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): From b7485763581ba0f8936fdc451d1c9fa5b08007c0 Mon Sep 17 00:00:00 2001 From: Cyrus Maden Date: Mon, 15 Jan 2018 13:36:44 -0800 Subject: [PATCH 3/9] Add name --- AUTHORS | 1 + 1 file changed, 1 insertion(+) 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 From 931e8830ba62a54c0158fd9a60af6b5f28fa1f11 Mon Sep 17 00:00:00 2001 From: Cyrus Maden Date: Thu, 18 Jan 2018 15:54:31 -0800 Subject: [PATCH 4/9] Update changelog Not issue ID. Will update with pr ID after submitting pr --- changelog/pr.doc | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelog/pr.doc diff --git a/changelog/pr.doc b/changelog/pr.doc new file mode 100644 index 00000000000..28e61c1d8bf --- /dev/null +++ b/changelog/pr.doc @@ -0,0 +1 @@ +Improve readability (wording, grammar) of Getting Started guide From cd76366d87eaaec6d04234c3d625c4506c058eaf Mon Sep 17 00:00:00 2001 From: Cyrus Maden Date: Thu, 18 Jan 2018 15:59:37 -0800 Subject: [PATCH 5/9] Rename pr.doc to 3131.doc --- changelog/{pr.doc => 3131.doc} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename changelog/{pr.doc => 3131.doc} (100%) diff --git a/changelog/pr.doc b/changelog/3131.doc similarity index 100% rename from changelog/pr.doc rename to changelog/3131.doc From ebb4c4715560bbf86b7cd328bef90b0c981bedc7 Mon Sep 17 00:00:00 2001 From: Cyrus Maden Date: Fri, 19 Jan 2018 18:44:33 -0800 Subject: [PATCH 6/9] Delete .DS_Store --- doc/.DS_Store | Bin 6148 -> 0 bytes 1 file changed, 0 insertions(+), 0 deletions(-) delete mode 100644 doc/.DS_Store diff --git a/doc/.DS_Store b/doc/.DS_Store deleted file mode 100644 index f72d921e6ac404f4ad650e931a05c7f1f695bc1d..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 6148 zcmeH~Jr2S!425lAKw|00n1usyg9yP1xB!B(As7&Qj?VKB1BDq?=vlJA*p1cp4NWZ~ zx_R_#kxoSBaHFg&3`~(vA!;KrJ4LH~3h_y_>bP Date: Fri, 19 Jan 2018 18:44:46 -0800 Subject: [PATCH 7/9] Delete .DS_Store --- doc/en/.DS_Store | Bin 6148 -> 0 bytes 1 file changed, 0 insertions(+), 0 deletions(-) delete mode 100644 doc/en/.DS_Store diff --git a/doc/en/.DS_Store b/doc/en/.DS_Store deleted file mode 100644 index f940bed6e384f5f76cd23313e2f8236eb972bc2c..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 6148 zcmeHKI|>3Z5S>vG!N$@uSMUZw^aLJ2(QSkU3$fqIb9pr1d;e&iX;6Vd)od{|=!lohtBGA;&_%QP(7ai*Ls7pS=NC^Gt$`e=02O#vU>M7p)&Dj8 zP5=K);))7Tfxl8fN2|?hi6>=k?LE$FZGrFLmUDxfVeS+RUXFoYjlb| WP3!`lj=0l-{24G^XjI_a3fut+K^1ra From 0b6df94b12a841a3de2fbced9e6d75c65f29761d Mon Sep 17 00:00:00 2001 From: Cyrus Maden Date: Fri, 19 Jan 2018 18:45:02 -0800 Subject: [PATCH 8/9] Delete .DS_Store --- .DS_Store | Bin 6148 -> 0 bytes 1 file changed, 0 insertions(+), 0 deletions(-) delete mode 100644 .DS_Store diff --git a/.DS_Store b/.DS_Store deleted file mode 100644 index 7cbe275046a42350e05301fa3e51caa9dcc81710..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 6148 zcmeH~Jr2S!425ml0g0s}V-^m;4I%_5-~tFbB6UFQIXcfj3xyd~=vlJA*s0a_4NWZ~ zdU%d|kwHY(aHH%j%uJDYGRh>k@o~Ffr|E7bw^h;#@Ihw#xlK?3DnJFO02QDD3sN8t z^7Upx&%{Te0#slb3fT9dz>PK8g8u11@DTv)QFg=HX9=)a0j$XuLtMpWxr-|5*!DDnJGPOabkW z=i>n{m1pb6>skGhRa-YW=$9kB{RAMfqj(E Date: Sat, 20 Jan 2018 11:12:59 -0800 Subject: [PATCH 9/9] Typo fix: "handeling" --> "handling" --- doc/en/getting-started.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/en/getting-started.rst b/doc/en/getting-started.rst index 3c6391c6a45..4a72844801a 100644 --- a/doc/en/getting-started.rst +++ b/doc/en/getting-started.rst @@ -160,7 +160,7 @@ List the name ``tmpdir`` in the test function signature and ``pytest`` will look PYTEST_TMPDIR/test_needsfiles0 1 failed in 0.12 seconds -More info on tmpdir handeling is available at `Temporary directories and files `_. +More info on tmpdir handling is available at `Temporary directories and files `_. Find out what kind of builtin ```pytest`` fixtures `_ exist with the command::