Home | History | Annotate | Download | only in 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 - Similarly, if you do not have "scp" in your system's $PATH then the
     97   multiplex scp tests will fail (since the system's shell startup scripts
     98   will determine where the shell started by sshd will look for scp).
     99 
    100 - Recent GNU coreutils deprecate "head -[n]": this will cause the yes-head
    101   test to fail.  The old behaviour can be restored by setting (and
    102   exporting) _POSIX2_VERSION=199209 before running the tests.
    103 
    104 $Id: README.regress,v 1.12 2011/05/05 03:48:42 djm Exp $
    105