This module provides a test framework for user acceptance testing (UAT) of command line or console applications. The framework establishes tmux sessions for test cases and provides functions for sending input to the tmux session and making assertions about the state of the terminal (i.e. what is on the screen).

Test cases (TestCase) are defined using withTmuxSession. The testTmux function groups test cases into a Tasty TestTree. Test cases are executed sequentially, each in a separate tmux session. Each test case can have a setup and teardown action, and there can also be a setup and teardown around the whole group of tests.

Let's look at a specific usage example. You want to test some program. There are two tests. Each test needs a dedicated temporary directory, but they also need a separate, shared temporary directory. We want the setup routines to create these directories and the teardown routines to remove them. Assume the existence of mkTempDir :: IO FilePath and rmDir :: FilePath -> IO ().

Looking first at testTmux:

data SharedEnv = SharedEnv FilePath

myTests :: TestTree
myTests = testTmux pre post [test1, test2]
  where
  pre = SharedEnv <$> mkTempDir
  post (SharedEnv path) = rmDir path

The shared setup action pre returns a SharedEnv value that will be propagated to each test case, as well as the teardown action, after all test cases have run.

test1 and test2 are defined thus:

test1 :: TestCase SharedEnv
test1 = withTmuxSession setup teardown "putFile" $ \step -> do
  -- test environment is availabe via ask
  TestEnv _ sharedDir testDir <- ask

  -- send a command to the tmux session and wait for "Done"
  sendLine ("myProg putFile " <> sharedDir) (Substring "Done.")

  -- save a snapshot of the terminal state and make some assertions
  snapshot
  assertSubstringS "The output should contain this substring"
  assertRegexS "The output should match this [Rr]eg[Ee]x"

test2 :: TestCase SharedEnv
test2 = withTmuxSession setup teardown "checkFile" $ \step -> do
  TestEnv _ sharedDir testDir <- ask

  -- use step to label different stages of the test
  step "Run program"
  sendLine ("myProg checkFile " <> sharedDir) (Substring "Yep, it's there.")

  step "Check exit code"
  sendLine "echo status $?" (Substring "status 0")

Further discussion of the setup action is warranted. This function, at minimum, must incorporate the TmuxSession argument into the value it returns. The type it returns must have an instance of HasTmuxSession; this provides the name of the tmux session to the framework functions that interact with tmux.

In our example, it also creates a per-test case temporary directory. The value returned by the setup action is provided to the teardown action.

data TestEnv = TestEnv
  { _session    :: TmuxSession
  , _sharedDir  :: FilePath
  , _testDir    :: FilePath
  }

instance HasTmuxSession TestEnv where
  tmuxSession = lens _session (\s b -> s { _session = b })

setup :: SharedEnv -> TmuxSession -> IO TestEnv
setup (SharedEnv sharedDir) session = TestEnv session sharedDir <$> mkTempDir

teardown :: TestEnv -> IO ()
teardown (TestEnv _ _ testDir) = rmDir testDir

If either shared or test-specific setup and teardown are not needed, the testTmux' and withTmuxSession' functions are provided for convenience.

tasty-tmux does not make any assumptions about terminal character encoding. The only exception is captureString which assumes UTF-8 encoding. All other functions deal with ByteString.

Be careful when using OverloadedStrings - the IsString instance for ByteString messes up characters > 127. If you need to include high characters in String or Regex assertions, encoding them using the expected terminal character encoding (you can encode in UTF-8 via encodeUtf8).