Initial check in of best-practice documentation for building test cases.

llvm-svn: 116964

lldb/docs/testsuite/best-practices.txt

@@ -0,0 +1,39 @@
+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.
+