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 TEST_SSH_PORT: TCP port to be used for the listening tests.
  32 TEST_SSH_SSH_CONFOPTS: Configuration directives to be added to ssh_config
  33         before running each test.
  34 TEST_SSH_SSHD_CONFOTPS: Configuration directives to be added to sshd_config
  35         before running each test.
  36
  37
  38 Individual tests.
  39
  40 You can run an individual test from the top-level Makefile, eg:
  41 $ make tests LTESTS=agent-timeout
  42
  43 If you need to manipulate the environment more you can invoke test-exec.sh
  44 directly if you set up the path to find the binaries under test and the
  45 test scripts themselves, for example:
  46
  47 $ cd regress
  48 $ PATH=`pwd`/..:$PATH:. TEST_SHELL=/bin/sh sh test-exec.sh `pwd` \
  49     agent-timeout.sh
  50 ok agent timeout test
  51
  52
  53 Files.
  54
  55 test-exec.sh: the main test driver. Sets environment, creates config files
  56 and keys and runs the specified test.
  57
  58 At the time of writing, the individual tests are:
  59 agent-timeout.sh:       agent timeout test
  60 agent.sh:               simple agent test
  61 broken-pipe.sh:         broken pipe test
  62 connect-privsep.sh:     proxy connect with privsep
  63 connect.sh:             simple connect
  64 exit-status.sh:         remote exit status
  65 forwarding.sh:          local and remote forwarding
  66 keygen-change.sh:       change passphrase for key
  67 keyscan.sh:             keyscan
  68 proto-mismatch.sh:      protocol version mismatch
  69 proto-version.sh:       sshd version with different protocol combinations
  70 proxy-connect.sh:       proxy connect
  71 sftp.sh:                basic sftp put/get
  72 ssh-com-client.sh:      connect with ssh.com client
  73 ssh-com-keygen.sh:      ssh.com key import
  74 ssh-com-sftp.sh:        basic sftp put/get with ssh.com server
  75 ssh-com.sh:             connect to ssh.com server
  76 stderr-after-eof.sh:    stderr data after eof
  77 stderr-data.sh:         stderr data transfer
  78 transfer.sh:            transfer data
  79 try-ciphers.sh:         try ciphers
  80 yes-head.sh:            yes pipe head
  81
  82
  83 Problems?
  84
  85 Run the failing test with shell tracing (-x) turned on:
  86 $ PATH=`pwd`/..:$PATH:. sh -x test-exec.sh `pwd` agent-timeout.sh
  87
  88 Failed tests can be difficult to diagnose. Suggestions:
  89 - run the individual test via ./test-exec.sh `pwd` [testname]
  90 - set LogLevel to VERBOSE in test-exec.sh and enable syslogging of
  91   auth.debug (eg to /var/log/authlog).
  92
  93
  94 Known Issues.
  95
  96 - If your build requires ssh-rand-helper regress tests will fail
  97   unless ssh-rand-helper is in pre-installed (the path to
  98   ssh-rand-helper is hard coded).
  99
 100 - Similarly, if you do not have "scp" in your system's $PATH then the
 101   multiplex scp tests will fail (since the system's shell startup scripts
 102   will determine where the shell started by sshd will look for scp).
 103
 104 - Recent GNU coreutils deprecate "head -[n]": this will cause the yes-head
 105   test to fail.  The old behaviour can be restored by setting (and
 106   exporting) _POSIX2_VERSION=199209 before running the tests.
 107
 108 $Id: README.regress,v 1.11 2010/08/16 21:04:29 djm Exp $