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 It is possible to restrict build and run lines to specific platforms using the BUILD(): syntax, for example
  14
  15     // BUILD(macos):    $CC main.c  -o $BUILD_DIR/example.exe
  16     // BUILD(ios):      $CC main.c -DIOS=1 -o $BUILD_DIR/example.exe
  17     // RUN(ios,macos):  ./example.exe
  18     int main() { return 0; }
  19
  20 will build example.exe with distinct options for macOS and iOS, and will invoke example.exe on both macOS and iOS (but not tvOS,
  21 watchOS, or bridgeOS). Valid platforms are "macos", ios", tvos", "watchos", "bridgeos".
  22
  23 When build lines are executed, the current directory is set to the test case's .dtest dir.
  24 Build lines may contain the follow variables:
  25     $BUILD_DIR    - expands to the directory in $DSTROOT where this test case binaries are installed
  26     $RUN_DIR      - expands to the directory in /AppleInternal/ where this test case binaries will be run
  27     $TEMP_DIR     - expands to a temporary directory that will be delete after this test case is built
  28     $CC           - expands to the C compiler command line for the current platform.  It includes
  29                     the min-os-version option, then SDK option, and the architectures.
  30     $CXX          - expands to the C++ compiler plus standard options
  31     $DEPENDS_ON   - adds a build time dependency to the next argument on the commandline
  32     $SKIP_INSTALL - prevents the built binary from being installed
  33     $SYM_LINK     - creates a symlink
  34     $CP           - copies a file
  35
  36 When run lines are executed, the current directory is set to what $RUN_DIR was during build.
  37 Run lines may contain the follow variables:
  38     $RUN_DIR       - expands to the directory in /AppleInternal/ where this test case binaries are installed
  39
  40
  41 The file "test_support.h" provides support functions to correctly write tests. The primariy interfaces provided are
  42 three printf like functions (technially they are implemented as macros in order to capture line info for logging):
  43
  44     void PASS(const char* format, ...);
  45     void FAIL(const char* format, ...);
  46     void LOG(const char* format, ...);
  47
  48 PASS() and FAIL() will take care of appropriately formatting the messages for the various test environments that dyld_tests
  49 run in. LOG() will capture messages in a per image queue. By default these logs are emitted if a test fails, and they are
  50 ignored if a test succeeds. While debugging tests logs can be emitted even during success by setting the LOG_ON_SUCCESS
  51 environment variable. This allows us to leave logging statements in production dyld_tests.Fdtra
  52
  53 Note, to run the tests as root, you need to first set "defaults write com.apple.dt.Xcode EnableRootTesting YES",
  54 and then check the "Debug process as root" box in the Test scheme on the ContainerizedTestRunner scheme.