An IO library for testing interactive command line programs.

Read this first:

• Tests using Proctests need to be compiled with -threaded for not blocking on process spawns.
• Beware that the Haskell GC closes process Handles after their last use. If you don't want to be surprised by this, use hClose where you want them to be closed (convenience: closeHandles). Really do this for EVERY process you create, the behaviour of a program writing to a closed handle is undefined. For example, getProcessExitCode run on such a program somtimes seems to always return ExitSuccess, no matter what the program actually does.
• Make sure handle buffering is set appropriately. run sets LineBuffering by default. Change it with setBuffering or hSetBuffering.
• Do not run the program in a shell (e.g. runInteractiveCommand) if you want to be able to terminate it reliably (terminateProcess). Use processes without shells (runInteractiveProcess) instead.

Example:

Let's say you want to test an interactive command line program like cat, and integrate your test into a test framework like Test.HSpec, using Test.HSpec.HUnit for the IO parts (remember that Proctest is stateful IO).

 main = hspec $ describe "cat" $ do

   it "prints out what we put in" $ do

     -- Start up the program to test
     (hIn, hOut, hErr, p) <- run "cat" []

     -- Make sure buffering doesn't prevent us from reading what we expect
     -- ('run' sets LineBuffering by default)
     setBuffering NoBuffering [hIn, hOut]

     -- Communicate with the program
     hPutStrLn hIn "hello world"

     -- Define a convenient wrapper around 'waitOutput'.
     --
     -- It specifies how long we have to wait
     -- (malfunctioning programs shall not block automated testing for too long)
     -- and how many bytes we are sure the expected response fits into
     -- (malfunctioning programs shall not flood us with garbage either).
     let catWait h = asUtf8Str <$> waitOutput (seconds 0.01) 1000 h -- Wait max 10 ms, 1000 bytes

     -- Wait a little to allow `cat` processing the input
     sleep (seconds 0.00001)

     -- Read the response
     response <- catWait hOut

     -- Test if it is what we want (here using HUnit's 'expectEqual')
     response @?= "hello world\n"