[libcxx-commits] [libcxx] 90455db - [libc++] NFC: Add documentation for writing tests

[Louis Dionne via libcxx-commits]

Author: Louis Dionne
Date: 2020-04-02T17:14:45-04:00
New Revision: 90455dbe2e74eb726f648ee84379eadfd850b3ed

URL: https://github.com/llvm/llvm-project/commit/90455dbe2e74eb726f648ee84379eadfd850b3ed
DIFF: https://github.com/llvm/llvm-project/commit/90455dbe2e74eb726f648ee84379eadfd850b3ed.diff

LOG: [libc++] NFC: Add documentation for writing tests

Added: 
    

Modified: 
    libcxx/docs/TestingLibcxx.rst

Removed: 
    


################################################################################
diff  --git a/libcxx/docs/TestingLibcxx.rst b/libcxx/docs/TestingLibcxx.rst
index 0dddfd6791a8..774003698bea 100644
--- a/libcxx/docs/TestingLibcxx.rst
+++ b/libcxx/docs/TestingLibcxx.rst
@@ -209,6 +209,29 @@ Environment Variables
   to use color diagnostic outputs from the compiler.
   Also see `color_diagnostics`.
 
+Writing Tests
+-------------
+
+When writing tests for the libc++ test suite, you should follow a few guidelines.
+This will ensure that your tests can run on a wide variety of hardware and under
+a wide variety of configurations. We have several unusual configurations such as
+building the tests on one host but running them on a 
diff erent host, which add a
+few requirements to the test suite. Here's some stuff you should know:
+
+- All tests are run in a temporary directory that is unique to that test and
+  cleaned up after the test is done.
+- When a test needs data files as inputs, these data files can be saved in the
+  repository (when reasonable) and referrenced by the test as
+  ``// FILE_DEPENDENCIES: <path-to-dependencies>``. Copies of these files or
+  directories will be made available to the test in the temporary directory
+  where it is run.
+- You should never hardcode a path from the build-host in a test, because that
+  path will not necessarily be available on the host where the tests are run.
+- You should try to reduce the runtime dependencies of each test to the minimum.
+  For example, requiring Python to run a test is bad, since Python is not
+  necessarily available on all devices we may want to run the tests on (even
+  though supporting Python is probably trivial for the build-host).
+
 Benchmarks
 ==========