Safe Haskell	Safe
Language	Haskell2010

Test.HUnitPlus.Filter

Description

Sets HUnit-Plus tests can be specified using Filters. These are used by Test.HUnitPlus.Execution and Test.HUnitPlus.Main to select which tests are run. Filters can specify tests belonging to a certain suite, starting with a certain path, having a certain tag, or combinations thereof.

Filters are optimized for the behavior of programs created by the createMain function, which runs a test if it matches any of the filters specified. There is also a string format for filters, which is how filters are specified in testlist files and command-line arguments. The format is optimized for simplicity, and as such, it is not necessarily possible to describe a given Filter with a single textual representation of a filter.

The format for filters is as follows:

[suite][path][tags][options]

Where at least one of the suite, path, tags, or options elements are present

The suite element is a comma-separated list of suite names (alphanumeric, no spaces), enclosed in brackets ('[' ']').

The path element is a series of path elements (alphanumeric, no spaces), separated by dots (.).

The tags element consists of a '@' character, followed by a comma-separated list of tag names (alphanumeric, no spaces).

The options element consists of a ? character, followed by a comma-separated list of "name"="value" bindings.

The following are examples of textual filters, and their meanings:

first.second.third: Run all tests starting with the path first.second.third. If there is a test named first.second.third, it will be run.
[unit]: Run all tests in the suite unit.
[unit,stress]: Run all tests in the suites unit and stress
@parser: Run all tests with the parser tag
@parser,lexer: Run all tests with the parser or the lexer tags.
backend.codegen@asm: Run all tests starting with the path backend.codegen with the asm tag.
[stress]@net: Run all tests in the stress suite with the tag net.
[perf,profile]inner.outer: Run all tests in the perf and profile suites that start with the path inner.outer.
[whitebox]network.protocol@security: Run all tests in the whitebox suite beginning with the path network.protocol that have the security tag.
first.second.third?"var"="val": Run all tests starting with the path first.second.third, with the option "var" set to "val".
[unit]?"timeout"="5": Run all tests in the suite unit with the option "timeout" set to "5".
[system]?"timeout"="5","threads"="4": Run all tests in the suite system with the option timeout set to '5' and threads set to '4'.
?"user"="jeffk": Run all tests with the user option set to jeffk.

The most common use case of filters is to select a single failing test to run, as part of fixing it. In this case, a single filter consisting of the path to the test will have this effect.

Synopsis

Documentation

data Selector Source #

A tree-like structure that represents a set of tests within a given suite.

Constructors

Selector

Fields

selectorInners :: HashMap Text Selector
Selectors for subgroups of this one. The entry for each path element contains the Selector to be used for that group (or test). An empty map actually means 'select all tests'.
selectorTags :: !(Maybe (HashSet Text))
Tags by which to filter all tests. The empty set actually means 'run all tests regardless of tags'. Nothing means that all tests will be skipped (though this will be overridden by any Selectors in selectorInners.

Instances

Eq Selector Source #
Methods (==) :: Selector -> Selector -> Bool # (/=) :: Selector -> Selector -> Bool #
Ord Selector Source #
Methods compare :: Selector -> Selector -> Ordering # (<) :: Selector -> Selector -> Bool # (<=) :: Selector -> Selector -> Bool # (>) :: Selector -> Selector -> Bool # (>=) :: Selector -> Selector -> Bool # max :: Selector -> Selector -> Selector # min :: Selector -> Selector -> Selector #
Show Selector Source #
Methods showsPrec :: Int -> Selector -> ShowS # show :: Selector -> String # showList :: [Selector] -> ShowS #
Hashable Selector Source #
Methods hashWithSalt :: Int -> Selector -> Int # hash :: Selector -> Int #

data Filter Source #

Specifies zero or more test suites, to which the given Selector is then applied. If no test suites are specified, then the Selector applies to all test suites.

Constructors

Filter
Fields filterSuites :: !(HashSet Text) The test suites to which the `Selector` applies. The empty set actually means 'all suites'. filterSelector :: !(HashSet Selector) The `Selector` to apply. filterOptions :: !(HashMap Text Text)

Instances

Eq Filter Source #
Methods (==) :: Filter -> Filter -> Bool # (/=) :: Filter -> Filter -> Bool #
Show Filter Source #
Methods showsPrec :: Int -> Filter -> ShowS # show :: Filter -> String # showList :: [Filter] -> ShowS #

type OptionMap = HashMap Text Text Source #

combineTags :: Maybe (HashSet Text) -> Maybe (HashSet Text) -> Maybe (HashSet Text) Source #

Combine two selectorTags fields into one. This operation represents the union of the tests that are selected by the two fields.

passFilter :: Filter Source #

A Filter that selects all tests in all suites.

allSelector :: Selector Source #

A Selector that selects all tests.

combineSelectors :: Selector -> Selector -> Selector Source #

Combine two Selectors into a single Selector.

suiteSelectors Source #

Arguments

:: [Text]	The names of all test suites.
-> [Filter]	The list of `Filter`s from which to build the map.
-> HashMap Text (HashMap OptionMap Selector)

Take a list of test suite names and a list of Filters, and build a HashMap that says for each test suite, what (combined) Selector should be used to select tests.

parseFilter Source #

Arguments

:: String	The name of the source.
-> Text	The input.
-> Either Text Filter

Parse a Filter expression. The format for filter expressions is described in the module documentation.

parseFilterFile :: FilePath -> IO (Either [Text] [Filter]) Source #

Given a FilePath, get the contents of the file and parse it as a testlist file.

parseFilterFileContent Source #

Arguments

:: String	The name of the input file.
-> Text	The file content.
-> Either [Text] [Filter]

Parse content from a testlist file. The file must contain one filter per line. Leading and trailing spaces are ignored, as are lines that contain no filter. A # will cause the parser to skip the rest of the line.