Test.Sandwich · sandwich-0.3.1.0

Sandwich is a test framework for Haskell. See the documentation for details and usage examples.

Running tests with command line args

3 declarations

These functions will read command line arguments when setting up your tests. These flags allow you filter the test tree, configure formatters, and pass your own custom options.

# Run using the terminal UI formatter, webdriver headless mode, filtering to nodes matching "Login"
stack run my-tests -- --tui --headless -f Login

valuerunSandwichWithCommandLineArgs :: Options -> TopSpecWithOptions -> IO ()

#

Run the spec, configuring the options from the command line.

valuerunSandwichWithCommandLineArgs'

:: Typeable a
=> Options
-> Parser a
-> TopSpecWithOptions' a
-> IO ()

#

Run the spec, configuring the options from the command line and adding user-configured command line options. The options will become available as a test context, which you can access by calling getCommandLineOptions.

valueparseCommandLineArgs

#

Running tests

2 declarations

valuerunSandwich :: Options -> CoreSpec -> IO ()

#

Run the spec with the given Options.

valuerunSandwich'

#

Run the spec with optional custom CommandLineOptions. When finished, return the exit reason, the number of "it" nodes which failed, and the total failed nodes (which includes "it" nodes, and may also include other nodes like "introduce" nodes).

Basic nodes

3 declarations

The basic building blocks of tests.

valueit

:: HasCallStack
=> String
Label for the example.
-> ExampleT context m ()
The test example
-> Free (SpecCommand context m) ()

#

Define a single test example.

valuedescribe

:: HasCallStack
=> String
Label for this group
-> SpecFree context m ()
Child spec tree
-> SpecFree context m ()

#

Define a group of tests.

valueparallel

:: HasCallStack
=> SpecFree context m ()
Child spec tree
-> SpecFree context m ()

#

Run a group of tests in parallel.

Context manager nodes

8 declarations

For introducing new contexts into tests and doing setup/teardown.

valueintroduce

:: (HasCallStack, Typeable intro)
=> String
String label for this node
-> Label l intro
Label under which to introduce the value
-> ExampleT context m intro
Action to produce the new value (of type intro)
-> (HasCallStack => intro -> ExampleT context m ())
Action to clean up the new value
-> SpecFree (LabelValue l intro :> context) m ()
Child spec tree
-> SpecFree context m ()

#

Introduce a new value and make it available to the child spec tree.

valueintroduceWith

:: HasCallStack
=> String
String label for this node
-> Label l intro
Label under which to introduce the value
-> ((HasCallStack => intro -> ExampleT context m [Result]) -> ExampleT context m ())
Callback to receive the new value and the child tree.
-> SpecFree (LabelValue l intro :> context) m ()
Child spec tree
-> SpecFree context m ()

#

Introduce a new value in an around fashion, so it can be used with context managers like withFile or bracket.

valuebefore

:: HasCallStack
=> String
Label for this context manager
-> ExampleT context m ()
Action to perform
-> SpecFree context m ()
Child spec tree
-> SpecFree context m ()

#

Perform an action before a given spec tree.

valuebeforeEach

:: HasCallStack
=> String
String label for this context manager
-> ExampleT context m ()
Action to perform
-> SpecFree context m ()
Child spec tree
-> SpecFree context m ()

#

Same as before, but applied individually to every it node.

valueafter

:: HasCallStack
=> String
Label for this context manager
-> ExampleT context m ()
Action to perform
-> SpecFree context m ()
Child spec tree
-> SpecFree context m ()

#

Perform an action after a given spec tree.

valueafterEach

:: HasCallStack
=> String
String label for this context manager
-> ExampleT context m ()
Action to perform
-> SpecFree context m ()
Child spec tree
-> SpecFree context m ()

#

Same as after, but applied individually to every it node.

valuearound

:: HasCallStack
=> String
-> (ExampleT context m [Result] -> ExampleT context m ())
Callback to run the child tree
-> SpecFree context m ()
Child spec tree
-> SpecFree context m ()

#

Run an action around the given child subtree. Useful for context managers like withFile or bracket.

valuearoundEach

:: (Monad m, HasCallStack)
=> String
String label for this context manager
-> (ExampleT context m [Result] -> ExampleT context m ())
Callback to run the child tree
-> SpecFree context m ()
Child spec tree
-> SpecFree context m ()

#

Same as around, but applied individually to every it node.

Parallel nodes

7 declarations

valuedefaultParallelNodeOptions :: NodeOptions

#

valueparallelN

:: MonadUnliftIO m
=> Int
-> SpecFree (LabelValue "parallelSemaphore" QSem :> context) m ()
-> SpecFree context m ()

#

Wrapper around parallel. Introduces a semaphore to limit the parallelism to N threads.

valueparallelN'

:: MonadUnliftIO m
=> NodeOptions
Node options
-> Int
Number of threads
-> SpecFree (LabelValue "parallelSemaphore" QSem :> context) m ()
-> SpecFree context m ()

#

valueparallelNFromArgs

:: (MonadUnliftIO m, HasCommandLineOptions context a)
=> (CommandLineOptions a -> Int)
Callback to extract the semaphore size
-> SpecFree (LabelValue "parallelSemaphore" QSem :> context) m ()
-> SpecFree context m ()

#

Same as parallelN, but extracts the semaphore size from the command line options.

valueparallelNFromArgs'

:: (MonadUnliftIO m, HasCommandLineOptions context a)
=> NodeOptions
Node options
-> (CommandLineOptions a -> Int)
Callback to extract the semaphore size
-> SpecFree (LabelValue "parallelSemaphore" QSem :> context) m ()
-> SpecFree context m ()

#

valueparallelSemaphore :: Label "parallelSemaphore" QSem

#

typetype HasParallelSemaphore context = HasLabel context "parallelSemaphore" QSem

#

Timing

4 declarations

For timing actions within your tests. Test tree nodes are timed by default.

valuetimeActionByProfile

:: (MonadUnliftIO m, MonadReader context m, HasTestTimer context)
=> ProfileName
Profile name
-> EventName
Event name
-> m a
-> m a

#

Time a given action with a given profile name and event name. Use when you want to manually specify the profile name.

valuetimeAction

:: (MonadUnliftIO m, HasBaseContextMonad context m, HasTestTimer context)
=> EventName
Event name
-> m a
-> m a

#

Time a given action with a given event name. This name will be the "stack frame" of the given action in the profiling results. This function will use the current timing profile name.

valuewithTimingProfile