testing/README.txt

   1
   2 When the dyld_tests target is built, all test cases are built into /AppleInternal/.
   3 A test case is a directory in $SRCROOT/testing/test-cases/ whose name ends in ".dtest".
   4 The build system reads any .c or .cxx files in the .dtest directory looking for BUILD: or RUN: lines.
   5 The BUILD: lines are use to build the test case binaries.
   6 The RUN: lines are used to build the information needed for BATS to run the test cases.
   7 Example, main.c may contain:
   8
   9     // BUILD:  $CC main.c  -o $BUILD_DIR/example.exe
  10     // RUN:  ./example.exe
  11     int main() { return 0; }
  12
  13 When build lines are executed, the current directory is set to the test case's .dtest dir.
  14 Build lines may contain the follow variables:
  15     $BUILD_DIR   - expands to the directory in $DSTROOT where this test case binaries are installed
  16     $RUN_DIR     - expands to the directory in /AppleInternal/ where this test case binaries will be run
  17     $TEMP_DIR    - expands to a temporary directory that will be delete after this test case is built
  18     $CC          - expands to the C compiler command line for the current platform.  It includes
  19                    the min-os-version option, then SDK option, and the architectures.
  20     $CXX         - expands to the C++ compiler plus standard options
  21
  22 When run lines are executed, the current directory is set to what $RUN_DIR was during build.
  23 Run lines may contain the follow variables:
  24     $RUN_DIR       - expands to the directory in /AppleInternal/ where this test case binaries are installed
  25     $REQUIRE_CRASH - expands to the 'nocr' tool which is used when a program is expected to "crash" in order to pass
  26
  27
  28 When a test program runs, it should initially print out the name of the test case. Ex:
  29  [BEGIN] dlfoo-thread-safe
  30 Then it should print a pass or fail message with the same test name. Ex:
  31  [PASS] dlfoo-thread-safe
  32
  33
  34 To support tests that dyld is supposed to terminate, use $REQUIRE_CRASH on the RUN: line
  35 along with setting env var NOCR_TEST_NAME to the name of the test case.  When that env
  36 var is set, the nocr tool wil print out the [BEGIN], then [PASS] if the test crashes
  37 otherwise [FAIL].  Ex:
  38   // RUN:  NOCR_TEST_NAME="dylib-static-link missing" $REQUIRE_CRASH ./dylib-static-missing.exe
  39
  40
  41 To support tests that are platform specific, add the BUILD_ONLY: line which specifies the platform.
  42 Valid platforms are: MacOSX, iOS, watchOS, and tvOS.  When a specific platform is specified, a
  43 new min OS version can also be specified via the BUILD_MIN_OS option.  For instance:
  44     // BUILD_ONLY: MacOSX
  45     // BUILD_MIN_OS: 10.5
  46
  47