xgupta updated this revision to Diff 369374.
xgupta added a comment.
Move testsuite/best-practice comtain to resources/test.
Repository:
rG LLVM Github Monorepo
CHANGES SINCE LAST ACTION
https://reviews.llvm.org/D108812/new/
https://reviews.llvm.org/D108812
Files:
lldb/docs/index.rst
lldb/docs/resources/test.rst
lldb/docs/testsuite/best-practices.rst
lldb/docs/testsuite/best-practices.txt
Index: lldb/docs/testsuite/best-practices.txt
===================================================================
--- 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 different data structures composed of float types to verify that what
-the debugger prints out matches what the compiler does for different 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.
Index: lldb/docs/testsuite/best-practices.rst
===================================================================
--- /dev/null
+++ lldb/docs/testsuite/best-practices.rst
@@ -0,0 +1,75 @@
+Best practices in writing testcases for LLDB
+============================================
+
+This document attempts to point out some best practices that prove to be helpful when building new test cases in the lldb/test
+directory. Everyone is welcomed to add/modify contents into this file.
+
+.. contents::
+ :local:
+
+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.
Index: lldb/docs/resources/test.rst
===================================================================
--- lldb/docs/resources/test.rst
+++ lldb/docs/resources/test.rst
@@ -319,6 +319,71 @@
# 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
-----------------
Index: lldb/docs/index.rst
===================================================================
--- lldb/docs/index.rst
+++ lldb/docs/index.rst
@@ -150,8 +150,7 @@
resources/test
resources/bots
resources/caveats
-
-
+
.. toctree::
:hidden:
:maxdepth: 1
_______________________________________________
lldb-commits mailing list
lldb-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
