From bfc9bbe8dfa45de218f08f599652258864db99ac Mon Sep 17 00:00:00 2001 From: Mavaddat Javid Date: Sat, 6 Feb 2021 15:08:27 -0800 Subject: [PATCH 1/5] Clarify, reorder language for TestCase(object) The former docstring inappropriately uses the term 'fixture' before introducing or defining the term. Therefore, I have re-arranged the description so that the definition comes before the usage. Additional semantic changes made to be clearer, more understandable, and linear. --- Lib/unittest/case.py | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/Lib/unittest/case.py b/Lib/unittest/case.py index 872f12112755e9..73b9997387c859 100644 --- a/Lib/unittest/case.py +++ b/Lib/unittest/case.py @@ -308,18 +308,20 @@ def __iter__(self): class TestCase(object): """A class whose instances are single test cases. - By default, the test code itself should be placed in a method named - 'runTest'. + Test authors should subclass this TestCase class for their own tests. + Testing code may be placed in subclass method named 'runTest'; + alternatively, invoke unittest.main() from the subclass's "__name__ guard" + section to run all methods defined in the test class. To achieve more + precise subclass test invocation see below (viz., constructor kwarg). - If the fixture may be used for many test cases, create as - many test methods as are needed. When instantiating such a TestCase - subclass, specify in the constructor arguments the name of the test method - that the instance is to execute. - - Test authors should subclass TestCase for their own tests. Construction - and deconstruction of the test's environment ('fixture') can be + Construction and destruction of the tests' environment ('fixture') can be implemented by overriding the 'setUp' and 'tearDown' methods respectively. + If the fixture will be used for several distinct test cases, create as + many test methods as needed in the TestCase subclass, then specify a + method to execute by providing the method name in the 'methodName' + kwarg of the instance constructor. + If it is necessary to override the __init__ method, the base class __init__ method must always be called. It is important that subclasses should not change the signature of their __init__ method, since instances @@ -331,8 +333,8 @@ class TestCase(object): the instance's assertion methods fail; test methods raising this exception will be deemed to have 'failed' rather than 'errored'. * longMessage: determines whether long messages (including repr of - objects used in assert methods) will be printed on failure in *addition* - to any explicit message passed. + objects used in assert methods) will be printed on failure in + *addition* to any explicit message passed. * maxDiff: sets the maximum length of a diff in failure messages by assert methods using difflib. It is looked up as an instance attribute so can be configured by individual tests if required. From ac87509c32a9a2ca6ff528bb7bfca0f69bf44f92 Mon Sep 17 00:00:00 2001 From: "blurb-it[bot]" <43283697+blurb-it[bot]@users.noreply.github.com> Date: Tue, 23 Jul 2024 20:18:32 +0000 Subject: [PATCH 2/5] =?UTF-8?q?=F0=9F=93=9C=F0=9F=A4=96=20Added=20by=20blu?= =?UTF-8?q?rb=5Fit.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../Documentation/2024-07-23-20-18-31.gh-issue-122196.pYwrvo.rst | 1 + 1 file changed, 1 insertion(+) create mode 100644 Misc/NEWS.d/next/Documentation/2024-07-23-20-18-31.gh-issue-122196.pYwrvo.rst diff --git a/Misc/NEWS.d/next/Documentation/2024-07-23-20-18-31.gh-issue-122196.pYwrvo.rst b/Misc/NEWS.d/next/Documentation/2024-07-23-20-18-31.gh-issue-122196.pYwrvo.rst new file mode 100644 index 00000000000000..29c3f8426fc487 --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2024-07-23-20-18-31.gh-issue-122196.pYwrvo.rst @@ -0,0 +1 @@ +The former docstring for `TestCase(object)` inappropriately uses the technical term 'fixture' before introducing or defining it. This violates the principle of term definition prior to usage. Therefore, I have re-arranged the description so that the definition comes before the usage. Additional semantic changes made to be clearer, more understandable, and linear. From 3d6943ad4a2b5c571c96f30613698359ae5c16dd Mon Sep 17 00:00:00 2001 From: Mavaddat Javid <5055400+mavaddat@users.noreply.github.com> Date: Thu, 29 Aug 2024 12:46:08 -0400 Subject: [PATCH 3/5] Update Lib/unittest/case.py Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- Lib/unittest/case.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Lib/unittest/case.py b/Lib/unittest/case.py index 9e07ebf9bd2e72..17f5596bb8aceb 100644 --- a/Lib/unittest/case.py +++ b/Lib/unittest/case.py @@ -387,8 +387,8 @@ class TestCase(object): the instance's assertion methods fail; test methods raising this exception will be deemed to have 'failed' rather than 'errored'. * longMessage: determines whether long messages (including repr of - objects used in assert methods) will be printed on failure in - *addition* to any explicit message passed. + objects used in assert methods) will be printed on failure in *addition* + to any explicit message passed. * maxDiff: sets the maximum length of a diff in failure messages by assert methods using difflib. It is looked up as an instance attribute so can be configured by individual tests if required. From e6ffc302f54042870ec6685ab3e6436601fbaa1a Mon Sep 17 00:00:00 2001 From: Mavaddat Javid <5055400+mavaddat@users.noreply.github.com> Date: Thu, 29 Aug 2024 12:57:24 -0400 Subject: [PATCH 4/5] Update Lib/unittest/case.py Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- Lib/unittest/case.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Lib/unittest/case.py b/Lib/unittest/case.py index 17f5596bb8aceb..ffea4833557f83 100644 --- a/Lib/unittest/case.py +++ b/Lib/unittest/case.py @@ -374,7 +374,7 @@ class TestCase(object): If the fixture will be used for several distinct test cases, create as many test methods as needed in the TestCase subclass, then specify a method to execute by providing the method name in the 'methodName' - kwarg of the instance constructor. + parameter of the instance constructor. If it is necessary to override the __init__ method, the base class __init__ method must always be called. It is important that subclasses From 9f1f18846e9f66a78eeec8fde4803864da273537 Mon Sep 17 00:00:00 2001 From: Mavaddat Javid <5055400+mavaddat@users.noreply.github.com> Date: Thu, 29 Aug 2024 16:39:45 -0400 Subject: [PATCH 5/5] Update case.py Re-order recommendations as suggested by https://github.com/python/cpython/pull/24465#discussion_r1688897655 --- Lib/unittest/case.py | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/Lib/unittest/case.py b/Lib/unittest/case.py index ffea4833557f83..7921b21687161b 100644 --- a/Lib/unittest/case.py +++ b/Lib/unittest/case.py @@ -362,11 +362,12 @@ def __iter__(self): class TestCase(object): """A class whose instances are single test cases. - Test authors should subclass this TestCase class for their own tests. + Test authors may invoke unittest.main() from the subclass's "__name__ guard" + section to run all methods defined in the test class. Alternatively, + test authors may subclass this TestCase class for their own tests. Testing code may be placed in subclass method named 'runTest'; - alternatively, invoke unittest.main() from the subclass's "__name__ guard" - section to run all methods defined in the test class. To achieve more - precise subclass test invocation see below (viz., constructor kwarg). + To achieve more precise subclass test invocation see below (viz., + constructor kwarg). Construction and destruction of the tests' environment ('fixture') can be implemented by overriding the 'setUp' and 'tearDown' methods respectively.