regress/README.regress

   1 Overview.
   2
   3 $ ./configure && make tests
   4
   5 You'll see some progress info. A failure will cause either the make to
   6 abort or the driver script to report a "FATAL" failure.
   7
   8 The test consists of 2 parts. The first is the file-based tests which is
   9 driven by the Makefile, and the second is a set of network or proxycommand
  10 based tests, which are driven by a driver script (test-exec.sh) which is
  11 called multiple times by the Makefile.
  12
  13 Failures in the first part will cause the Makefile to return an error.
  14 Failures in the second part will print a "FATAL" message for the failed
  15 test and continue.
  16
  17 OpenBSD has a system-wide regression test suite. OpenSSH Portable's test
  18 suite is based on OpenBSD's with modifications.
  19
  20
  21 Environment variables.
  22
  23 SUDO: path to sudo command, if desired. Note that some systems (notably
  24         systems using PAM) require sudo to execute some tests.
  25 TEST_SSH_TRACE: set to "yes" for verbose output from tests
  26 TEST_SSH_QUIET: set to "yes" to suppress non-fatal output.
  27 TEST_SSH_x: path to "ssh" command under test, where x=SSH,SSHD,SSHAGENT,SSHADD
  28         SSHKEYGEN,SSHKEYSCAN,SFTP,SFTPSERVER
  29 OBJ: used by test scripts to access build dir.
  30 TEST_SHELL: shell used for running the test scripts.
  31
  32
  33 Individual tests.
  34
  35 You can invoke test-exec.sh directly if you set up the path to find the
  36 binaries under test and the test scripts themselves, for example:
  37
  38 $ cd regress
  39 $ PATH=`pwd`/..:$PATH:. TEST_SHELL=/bin/sh sh test-exec.sh `pwd` \
  40     agent-timeout.sh
  41 ok agent timeout test
  42
  43
  44 Files.
  45
  46 test-exec.sh: the main test driver. Sets environment, creates config files
  47 and keys and runs the specified test.
  48
  49 At the time of writing, the individual tests are:
  50 agent-timeout.sh:       agent timeout test
  51 agent.sh:               simple agent test
  52 broken-pipe.sh:         broken pipe test
  53 connect-privsep.sh:     proxy connect with privsep
  54 connect.sh:             simple connect
  55 exit-status.sh:         remote exit status
  56 forwarding.sh:          local and remote forwarding
  57 keygen-change.sh:       change passphrase for key
  58 keyscan.sh:             keyscan
  59 proto-mismatch.sh:      protocol version mismatch
  60 proto-version.sh:       sshd version with different protocol combinations
  61 proxy-connect.sh:       proxy connect
  62 sftp.sh:                basic sftp put/get
  63 ssh-com-client.sh:      connect with ssh.com client
  64 ssh-com-keygen.sh:      ssh.com key import
  65 ssh-com-sftp.sh:        basic sftp put/get with ssh.com server
  66 ssh-com.sh:             connect to ssh.com server
  67 stderr-after-eof.sh:    stderr data after eof
  68 stderr-data.sh:         stderr data transfer
  69 transfer.sh:            transfer data
  70 try-ciphers.sh:         try ciphers
  71 yes-head.sh:            yes pipe head
  72
  73
  74 Problems?
  75
  76 Run the failing test with shell tracing (-x) turned on:
  77 $ PATH=`pwd`/..:$PATH:. sh -x test-exec.sh `pwd` agent-timeout.sh
  78
  79 Failed tests can be difficult to diagnose. Suggestions:
  80 - run the individual test via ./test-exec.sh `pwd` [testname]
  81 - set LogLevel to VERBOSE in test-exec.sh and enable syslogging of
  82   auth.debug (eg to /var/log/authlog).
  83
  84
  85 Known Issues.
  86
  87 - If you build with tcpwrappers and try to run the regression tests,
  88   your hosts.allow must permit connections from localhost and from
  89   "unknown".  This is because some tests are performed via the loopback
  90   interface, while others are done with "sshd -i" as a ProxyCommand.  In
  91   the latter case, when sshd calls getpeername() on the socket it will
  92   fail (because it's not a tcp socket) and will be identified as
  93   "unknown", which is then checked against tcpwrappers.
  94
  95 - If your build requires ssh-rand-helper regress tests will fail
  96   unless ssh-rand-helper is in pre-installed (the path to
  97   ssh-rand-helper is hard coded).
  98
  99 $Id$