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     $DEPENDS_ON   - adds a build time dependency to the next argument on the commandline
  22     $SKIP_INSTALL - prevents the built binary from being installed
  23     $SYM_LINK     - creates a symlink
  24     $CP           - copies a file
  25
  26 When run lines are executed, the current directory is set to what $RUN_DIR was during build.
  27 Run lines may contain the follow variables:
  28     $RUN_DIR       - expands to the directory in /AppleInternal/ where this test case binaries are installed
  29
  30
  31 The file "test_support.h" provides support functions to correctly write tests. The primariy interfaces provided are
  32 three printf like functions (technially they are implemented as macros in order to capture line info for logging):
  33
  34     void PASS(const char* format, ...);
  35     void FAIL(const char* format, ...);
  36     void LOG(const char* format, ...);
  37
  38 PASS() and FAIL() will take care of appropriately formatting the messages for the various test environments that dyld_tests
  39 run in. LOG() will capture messages in a per image queue. By default these logs are emitted if a test fails, and they are
  40 ignored if a test succeeds. While debugging tests logs can be emitted even during success by setting the LOG_ON_SUCCESS
  41 environment variable. This allows us to leave logging statements in production dyld_tests.Fdtra
  42
  43 To support tests that are platform specific, add the BUILD_ONLY: line which specifies the platform.
  44 Valid platforms are: MacOSX, iOS, watchOS, and tvOS.  When a specific platform is specified, a
  45 new min OS version can also be specified via the BUILD_MIN_OS option.  For instance:
  46     // BUILD_ONLY: MacOSX
  47     // BUILD_MIN_OS: 10.5
  48
  49 Note, to run the tests as root, you need to first set "defaults write com.apple.dt.Xcode EnableRootTesting YES",
  50 and then check the "Debug process as root" box in the Test scheme on the ContainerizedTestRunner scheme.