[Lldb-commits] [lldb] 654e8d6 - [LLDB][Docs] Move best-practices.txt contain to resources/test.rst

[Shivam Gupta via lldb-commits]

Author: Shivam Gupta
Date: 2021-08-31T11:45:24+05:30
New Revision: 654e8d6c318a0c4eb9bfd74a9ace6d1a1bda5100

URL: https://github.com/llvm/llvm-project/commit/654e8d6c318a0c4eb9bfd74a9ace6d1a1bda5100
DIFF: https://github.com/llvm/llvm-project/commit/654e8d6c318a0c4eb9bfd74a9ace6d1a1bda5100.diff

LOG: [LLDB][Docs] Move best-practices.txt contain to resources/test.rst

This file contain some old reference to files those are now either renamed or replaced.
Also this .txt file didn't generate to html during the sphnix documentation build so I send its contents to resources/test.rst file.

Signed-off-by: Shivam Gupta <shivam98.tkg at gmail.com>

Reviewed By: teemperor, mgorny, JDevlieghere

Differential Revision: https://reviews.llvm.org/D108812

Added: 
    

Modified: 
    lldb/docs/resources/test.rst

Removed: 
    lldb/docs/testsuite/best-practices.txt


################################################################################
diff  --git a/lldb/docs/resources/test.rst b/lldb/docs/resources/test.rst
index d2830bc53c1f0..1f876ff4513d6 100644
--- a/lldb/docs/resources/test.rst
+++ b/lldb/docs/resources/test.rst
@@ -319,6 +319,71 @@ A better way to write the test above would be using LLDB's testing function
     # Good. Will print expected_string and the contents of list_of_results.
     self.assertIn(expected_string, list_of_results)
 
+**Do not use hard-coded line numbers in your test case.**
+
+Instead, try to tag the line with some distinguishing pattern, and use the function line_number() defined in lldbtest.py which takes 
+filename and string_to_match as arguments and returns the line number.
+
+As an example, take a look at test/API/functionalities/breakpoint/breakpoint_conditions/main.c which has these
+two lines:
+
+.. code-block:: c
+
+        return c(val); // Find the line number of c's parent call here.
+
+and
+
+.. code-block:: c
+
+    return val + 3; // Find the line number of function "c" here.
+
+The Python test case TestBreakpointConditions.py uses the comment strings to find the line numbers during setUp(self) and use them
+later on to verify that the correct breakpoint is being stopped on and that its parent frame also has the correct line number as
+intended through the breakpoint condition.
+
+**Take advantage of the unittest framework's decorator features.**
+
+These features can be use to properly mark your test class or method for platform-specific tests, compiler specific, version specific.
+
+As an example, take a look at test/API/lang/c/forward/TestForwardDeclaration.py which has these lines:
+
+.. code-block:: python
+
+    @no_debug_info_test
+    @skipIfDarwin
+    @skipIf(compiler=no_match("clang"))
+    @skipIf(compiler_version=["<", "8.0"])
+    @expectedFailureAll(oslist=["windows"])
+    def test_debug_names(self):
+        """Test that we are able to find complete types when using DWARF v5
+        accelerator tables"""
+        self.do_test(dict(CFLAGS_EXTRAS="-gdwarf-5 -gpubnames"))
+
+This tells the test harness that unless we are running "linux" and clang version equal & above 8.0, the test should be skipped.
+
+**Class-wise cleanup after yourself.**
+
+TestBase.tearDownClass(cls) provides a mechanism to invoke the platform-specific cleanup after finishing with a test class. A test
+class can have more than one test methods, so the tearDownClass(cls) method gets run after all the test methods have been executed by
+the test harness.
+
+The default cleanup action performed by the packages/Python/lldbsuite/test/lldbtest.py module invokes the "make clean" os command.
+
+If this default cleanup is not enough, individual class can provide an extra cleanup hook with a class method named classCleanup , 
+for example, in test/API/terminal/TestSTTYBeforeAndAfter.py:
+
+.. code-block:: python
+
+    @classmethod
+    def classCleanup(cls):
+        """Cleanup the test byproducts."""
+        cls.RemoveTempFile("child_send1.txt")
+
+
+The 'child_send1.txt' file gets generated during the test run, so it makes sense to explicitly spell out the action in the same 
+TestSTTYBeforeAndAfter.py file to do the cleanup instead of artificially adding it as part of the default cleanup action which serves to
+cleanup those intermediate and a.out files.
+
 Running The Tests
 -----------------
 

diff  --git a/lldb/docs/testsuite/best-practices.txt b/lldb/docs/testsuite/best-practices.txt
deleted file mode 100644
index b5a9156fd521c..0000000000000
--- a/lldb/docs/testsuite/best-practices.txt
+++ /dev/null
@@ -1,93 +0,0 @@
-This document attempts to point out some best practices that prove to be helpful
-when building new test cases in the tot/test directory.  Everyone is welcomed to
-add/modify contents into this file.
-
-o Do not use hard-coded line numbers in your test case.  Instead, try to tag the
-  line with some distinguishing pattern, and use the function line_number()
-  defined in lldbtest.py which takes filename and string_to_match as arguments
-  and returns the line number.
-
-As an example, take a look at test/breakpoint_conditions/main.c which has these
-two lines:
-
-        return c(val); // Find the line number of c's parent call here.
-
-and
-
-    return val + 3; // Find the line number of function "c" here.
-
-The Python test case TestBreakpointConditions.py uses the comment strings to
-find the line numbers during setUp(self) and use them later on to verify that
-the correct breakpoint is being stopped on and that its parent frame also has
-the correct line number as intended through the breakpoint condition.
-
-o Take advantage of the unittest framework's decorator features to properly
-  mark your test class or method for platform-specific tests.
-
-As an example, take a look at test/forward/TestForwardDeclaration.py which has
-these lines:
-
-    @unittest2.skipUnless(sys.platform.startswith("darwin"), "requires Darwin")
-    def test_with_dsym_and_run_command(self):
-        """Display *bar_ptr when stopped on a function with forward declaration of struct bar."""
-        self.buildDsym()
-        self.forward_declaration()
-
-This tells the test harness that unless we are running "darwin", the test should
-be skipped.  This is because we are asking to build the binaries with dsym debug
-info, which is only available on the darwin platforms.
-
-o Cleanup after yourself.  A classic example of this can be found in test/types/
-  TestFloatTypes.py:
-
-    def test_float_types_with_dsym(self):
-        """Test that float-type variables are displayed correctly."""
-        d = {'CXX_SOURCES': 'float.cpp'}
-        self.buildDsym(dictionary=d)
-        self.setTearDownCleanup(dictionary=d)
-        self.float_type()
-
-    ...
-
-    def test_double_type_with_dsym(self):
-        """Test that double-type variables are displayed correctly."""
-        d = {'CXX_SOURCES': 'double.cpp'}
-        self.buildDsym(dictionary=d)
-        self.setTearDownCleanup(dictionary=d)
-        self.double_type()
-
-This tests 
diff erent data structures composed of float types to verify that what
-the debugger prints out matches what the compiler does for 
diff erent variables
-of these types.  We're using a dictionary to pass the build parameters to the
-build system.  After a particular test instance is done, it is a good idea to
-clean up the files built.  This eliminates the chance that some leftover files
-can interfere with the build phase for the next test instance and render it
-invalid.
-
-TestBase.setTearDownCleanup(self, dictionary) defined in lldbtest.py is created
-to cope with this use case by taking the same build parameters in order to do
-the cleanup when we are finished with a test instance, during
-TestBase.tearDown(self).
-
-o Class-wise cleanup after yourself.
-
-TestBase.tearDownClass(cls) provides a mechanism to invoke the platform-specific
-cleanup after finishing with a test class. A test class can have more than one
-test methods, so the tearDownClass(cls) method gets run after all the test
-methods have been executed by the test harness.
-
-The default cleanup action performed by the plugins/darwin.py module invokes the
-"make clean" os command.
-
-If this default cleanup is not enough, individual class can provide an extra
-cleanup hook with a class method named classCleanup , for example,
-in test/breakpoint_command/TestBreakpointCommand.py:
-
-    @classmethod
-    def classCleanup(cls):
-        system(["/bin/sh", "-c", "rm -f output.txt"])
-
-The 'output.txt' file gets generated during the test run, so it makes sense to
-explicitly spell out the action in the same TestBreakpointCommand.py file to do
-the cleanup instead of artificially adding it as part of the default cleanup
-action which serves to cleanup those intermediate and a.out files.