winsup/testsuite/README

   1 Here are some notes about adding to and using this testsuite.
   2
   3 The testsuite adds a directory containing the just-built cygwin1.dll to the PATH
   4 so that it can be found by the Windows loader during testing.
   5
   6 Because we'll probably run into complaints about using two DLLs, we use
   7 cygrun.exe to run each test.  All this does is run the test with CreateProcess()
   8 so that we don't attempt to do the special code for when a cygwin program calls
   9 another cygwin program, as this might be a "multiple cygwins" problem.
  10
  11 The testsuite/winsup.api subdirectory is for testing the API to cygwin1.dll
  12 ONLY.  Create other subdirs under testsuite/ for other classes of testing.
  13
  14 Tests in testsuite/winsup.api/pthread/ are derived from the pthread-win32
  15 testsuite.
  16
  17 Tests in testsuite/winsup.api/ltp/ are derived from (a very old version of) the
  18 ltp testsuite.
  19
  20 Don't print anything to the screen if you can avoid it (except for failure
  21 reasons, of course).
  22
  23 "make check" will only work if you run it *on* an NT machine.  Cross-checking is
  24 not supported.
  25
  26 Tests whose name is mentioned in XFAIL_TESTS are expected to fail, effectively
  27 reversing the result of those.
  28
  29 Adding a test
  30 =============
  31
  32 Add the source for the test under testsuite/winsup.api/.
  33
  34 Add the additional tests program to check_PROGRAMS in testsuite/Makefile.am.
  35
  36 (Note that if the test 'foo' has a single source file, foo.c, there's no need to
  37 write a foo_SOURCES as that's the default Automake assumes.)
  38
  39 Tests can use libltp, but's that not required.
  40
  41 The Cygwin 'installation' that the tests are run in is minimal, so don't assume
  42 anything is present.
  43
  44 Any test that needs to test command line args or redirection needs to run such a
  45 child program itself, as the testsuite will not do any arguments or redirection
  46 for it.  Same for fork, signals, etc.
  47
  48 Tests should either run successfully and exit(0), exit(77) to indicate a skipped
  49 test, or any other exit status to indicate a failure.
  50
  51 Tips
  52 ====
  53
  54 * To run selected tests, use e.g:
  55
  56 $ make check TESTS="winsup.api/ltp/umask03 winsup.api/ltp/stat06"
  57
  58 * To build the tests without running them, use the check_programs target, e.g:
  59
  60 $ make -C winsup/testsuite/ check_programs
  61
  62 * To run an individual test program directly (against the installed, rather than
  63   just built DLL), e.g.:
  64
  65 $ winsup/testsuite/winsup.api/pthread/cancel1
  66
  67 * To run an individual test program against the test DLL under gdb, e.g.:
  68
  69 $ PATH="<build_tooldir>/winsup/testsuite/testinst/bin/:$PATH" cygrun -notimeout "gdb winsup.api/systemcall"