From 0194f90d0e7118d44f0e3b0750eb69035811e2b8 Mon Sep 17 00:00:00 2001 From: Tom Hughes Date: Thu, 26 Jan 2023 09:04:01 -0800 Subject: [PATCH] Fix Python docstrings to match style guide https://google.github.io/styleguide/pyguide.html#s3.8.3-functions-and-methods PiperOrigin-RevId: 504857416 Change-Id: I7815ce27e454a120b3974ae7e2bea952108b836c --- .../googletest-break-on-failure-unittest.py | 8 +++- .../test/googletest-list-tests-unittest.py | 8 +++- googletest/test/googletest-output-test.py | 7 ++- .../test/googletest-throw-on-failure-test.py | 12 ++++- googletest/test/gtest_help_test.py | 8 +++- googletest/test/gtest_xml_output_unittest.py | 34 ++++++++++---- googletest/test/gtest_xml_test_utils.py | 44 ++++++++++++------- 7 files changed, 88 insertions(+), 33 deletions(-) diff --git a/googletest/test/googletest-break-on-failure-unittest.py b/googletest/test/googletest-break-on-failure-unittest.py index 3f65812b..e314b5cc 100755 --- a/googletest/test/googletest-break-on-failure-unittest.py +++ b/googletest/test/googletest-break-on-failure-unittest.py @@ -88,13 +88,17 @@ def Run(command): class GTestBreakOnFailureUnitTest(gtest_test_utils.TestCase): - """Tests using the GTEST_BREAK_ON_FAILURE environment variable or + """Unit test for Google Test's break-on-failure mode. + + Tests using the GTEST_BREAK_ON_FAILURE environment variable or the --gtest_break_on_failure flag to turn assertion failures into segmentation faults. """ def RunAndVerify(self, env_var_value, flag_value, expect_seg_fault): - """Runs googletest-break-on-failure-unittest_ and verifies that it does + """Runs googletest-break-on-failure-unittest_ and verifies its behavior. + + Runs googletest-break-on-failure-unittest_ and verifies that it does (or does not) have a seg-fault. Args: diff --git a/googletest/test/googletest-list-tests-unittest.py b/googletest/test/googletest-list-tests-unittest.py index f59fca01..977e57f0 100755 --- a/googletest/test/googletest-list-tests-unittest.py +++ b/googletest/test/googletest-list-tests-unittest.py @@ -132,7 +132,9 @@ class GTestListTestsUnitTest(gtest_test_utils.TestCase): """Tests using the --gtest_list_tests flag to list all tests.""" def RunAndVerify(self, flag_value, expected_output_re, other_flag): - """Runs googletest-list-tests-unittest_ and verifies that it prints + """Run googletest-list-tests-unittest_ and verify the output. + + Runs googletest-list-tests-unittest_ and verifies that it prints the correct tests. Args: @@ -206,7 +208,9 @@ class GTestListTestsUnitTest(gtest_test_utils.TestCase): ) def testWithFilterFlags(self): - """Tests that --gtest_list_tests takes into account the + """Tests that --gtest_list_tests takes into account the filter flags. + + Tests that --gtest_list_tests takes into account the --gtest_filter flag. """ diff --git a/googletest/test/googletest-output-test.py b/googletest/test/googletest-output-test.py index 5185ed97..347b8546 100755 --- a/googletest/test/googletest-output-test.py +++ b/googletest/test/googletest-output-test.py @@ -237,13 +237,16 @@ def GetShellCommandOutput(env_cmd): def GetCommandOutput(env_cmd): - """Runs a command and returns its output with all file location - info stripped off. + """Runs a command and returns output with all file location info stripped off. Args: env_cmd: The shell command. A 2-tuple where element 0 is a dict of extra environment variables to set, and element 1 is a string with the command and any flags. + + Returns: + A string with the command's combined standard and diagnostic output. File + location info is stripped. """ # Disables exception pop-ups on Windows. diff --git a/googletest/test/googletest-throw-on-failure-test.py b/googletest/test/googletest-throw-on-failure-test.py index 282163bc..106b0044 100755 --- a/googletest/test/googletest-throw-on-failure-test.py +++ b/googletest/test/googletest-throw-on-failure-test.py @@ -55,8 +55,14 @@ EXE_PATH = gtest_test_utils.GetTestExecutablePath( def SetEnvVar(env_var, value): - """Sets an environment variable to a given value; unsets it when the + """Sets an environment variable. + + Sets an environment variable to a given value; unsets it when the given value is None. + + Args: + env_var: environment variable. + value: value to set. """ env_var = env_var.upper() @@ -79,7 +85,9 @@ class ThrowOnFailureTest(gtest_test_utils.TestCase): """Tests the throw-on-failure mode.""" def RunAndVerify(self, env_var_value, flag_value, should_fail): - """Runs googletest-throw-on-failure-test_ and verifies that it does + """Runs googletest-throw-on-failure-test_ and verifies its behavior. + + Runs googletest-throw-on-failure-test_ and verifies that it does (or does not) exit with a non-zero code. Args: diff --git a/googletest/test/gtest_help_test.py b/googletest/test/gtest_help_test.py index 1d674158..fda40bff 100755 --- a/googletest/test/gtest_help_test.py +++ b/googletest/test/gtest_help_test.py @@ -187,14 +187,18 @@ class GTestHelpTest(gtest_test_utils.TestCase): self.TestHelpFlag(UNKNOWN_GTEST_PREFIXED_FLAG) def testRunsTestsWithoutHelpFlag(self): - """Verifies that when no help flag is specified, the tests are run + """Verifies correct behavior when no help flag is specified. + + Verifies that when no help flag is specified, the tests are run and the help message is not printed. """ self.TestNonHelpFlag(None) def testRunsTestsWithGtestInternalFlag(self): - """Verifies that the tests are run and no help message is printed when + """Verifies correct behavior when internal testing flag is specified. + + Verifies that the tests are run and no help message is printed when a flag starting with Google Test prefix and 'internal_' is supplied. """ diff --git a/googletest/test/gtest_xml_output_unittest.py b/googletest/test/gtest_xml_output_unittest.py index d48d1af2..e46ad399 100755 --- a/googletest/test/gtest_xml_output_unittest.py +++ b/googletest/test/gtest_xml_output_unittest.py @@ -246,7 +246,8 @@ class GTestXMLOutputUnitTest(gtest_xml_test_utils.GTestXMLTestCase): # type-parameterized tests, so we don't run it under them. if SUPPORTS_TYPED_TESTS: def testNonEmptyXmlOutput(self): - """ + """Generates non-empty XML and verifies it matches the expected output. + Runs a test program that generates a non-empty XML output, and tests that the XML output is expected. """ @@ -286,7 +287,8 @@ class GTestXMLOutputUnitTest(gtest_xml_test_utils.GTestXMLTestCase): actual.unlink() def testDefaultOutputFile(self): - """ + """Tests XML file with default name is created when name is not specified. + Confirms that Google Test produces an XML output file with the expected default name if no name is explicitly specified. """ @@ -309,7 +311,8 @@ class GTestXMLOutputUnitTest(gtest_xml_test_utils.GTestXMLTestCase): self.assertTrue(os.path.isfile(output_file)) def testSuppressedXmlOutput(self): - """ + """Verifies XML output is suppressed if default listener is shut down. + Tests that no XML file is generated if the default XML listener is shut down before RUN_ALL_TESTS is invoked. """ @@ -363,11 +366,18 @@ class GTestXMLOutputUnitTest(gtest_xml_test_utils.GTestXMLTestCase): extra_env={SHARD_INDEX_ENV_VAR: '0', TOTAL_SHARDS_ENV_VAR: '10'}) - def _GetXmlOutput(self, gtest_prog_name, extra_args, extra_env, - expected_exit_code): - """ - Returns the xml output generated by running the program gtest_prog_name. + def _GetXmlOutput( + self, gtest_prog_name, extra_args, extra_env, expected_exit_code + ): + """Returns the XML output generated by running the program gtest_prog_name. + Furthermore, the program's exit code must be expected_exit_code. + + Args: + gtest_prog_name: Program to run. + extra_args: Optional arguments to pass to program. + extra_env: Optional environment variables to set. + expected_exit_code: Expected exit code from running gtest_prog_name. """ xml_path = os.path.join(gtest_test_utils.GetTempDir(), gtest_prog_name + 'out.xml') @@ -398,11 +408,19 @@ class GTestXMLOutputUnitTest(gtest_xml_test_utils.GTestXMLTestCase): def _TestXmlOutput(self, gtest_prog_name, expected_xml, expected_exit_code, extra_args=None, extra_env=None): - """ + """Asserts that the XML document matches. + Asserts that the XML document generated by running the program gtest_prog_name matches expected_xml, a string containing another XML document. Furthermore, the program's exit code must be expected_exit_code. + + Args: + gtest_prog_name: Program to run. + expected_xml: Path to XML document to match. + expected_exit_code: Expected exit code from running gtest_prog_name. + extra_args: Optional arguments to pass to program. + extra_env: Optional environment variables to set. """ actual = self._GetXmlOutput(gtest_prog_name, extra_args or [], diff --git a/googletest/test/gtest_xml_test_utils.py b/googletest/test/gtest_xml_test_utils.py index ae41bbad..567a3141 100755 --- a/googletest/test/gtest_xml_test_utils.py +++ b/googletest/test/gtest_xml_test_utils.py @@ -40,9 +40,9 @@ class GTestXMLTestCase(gtest_test_utils.TestCase): Base class for tests of Google Test's XML output functionality. """ - def AssertEquivalentNodes(self, expected_node, actual_node): - """ + """Asserts that actual_node is equivalent to expected_node. + Asserts that actual_node (a DOM node object) is equivalent to expected_node (another DOM node object), in that either both of them are CDATA nodes and have the same value, or both are DOM @@ -58,6 +58,10 @@ class GTestXMLTestCase(gtest_test_utils.TestCase): CDATA sections) as expected_node. Note that we ignore the order of the children as they are not guaranteed to be in any particular order. + + Args: + expected_node: expected DOM node object + actual_node: actual DOM node object """ if expected_node.nodeType == Node.CDATA_SECTION_NODE: @@ -126,18 +130,24 @@ class GTestXMLTestCase(gtest_test_utils.TestCase): } def _GetChildren(self, element): - """ - Fetches all of the child nodes of element, a DOM Element object. - Returns them as the values of a dictionary keyed by the IDs of the - children. For , , , and - elements, the ID is the value of their "name" attribute; for - elements, it is the value of the "message" attribute; for - elements, it is the value of their parent's "name" attribute plus the - literal string "properties"; CDATA sections and non-whitespace - text nodes are concatenated into a single CDATA section with ID - "detail". An exception is raised if any element other than the above - four is encountered, if two child elements with the same identifying - attributes are encountered, or if any other type of node is encountered. + """Fetches all of the child nodes of element, a DOM Element object. + + Returns them as the values of a dictionary keyed by the IDs of the children. + For , , , and elements, the ID + is the value of their "name" attribute; for elements, it is the + value of the "message" attribute; for elements, it is the value + of their parent's "name" attribute plus the literal string "properties"; + CDATA sections and non-whitespace text nodes are concatenated into a single + CDATA section with ID "detail". An exception is raised if any element other + than the above four is encountered, if two child elements with the same + identifying attributes are encountered, or if any other type of node is + encountered. + + Args: + element: DOM Element object + + Returns: + Dictionary where keys are the IDs of the children. """ children = {} @@ -171,7 +181,8 @@ class GTestXMLTestCase(gtest_test_utils.TestCase): return children def NormalizeXml(self, element): - """ + """Normalizes XML that may change from run to run. + Normalizes Google Test's XML output to eliminate references to transient information that may change from run to run. @@ -188,6 +199,9 @@ class GTestXMLTestCase(gtest_test_utils.TestCase): file's basename and a single asterisk for the line number. * The directory names in file paths are removed. * The stack traces are removed. + + Args: + element: DOM element to normalize """ if element.tagName == 'testcase':