Test.HUnitPlus.Filter

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.

Documentation

data Selector

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

Methods

(==) :: Selector -> Selector -> Bool

(/=) :: Selector -> Selector -> Bool

Ord Selector

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

Methods

showsPrec :: Int -> Selector -> ShowS

show :: Selector -> String

showList :: [Selector] -> ShowS

Hashable Selector

Methods

hashWithSalt :: Int -> Selector -> Int

hash :: Selector -> Int

data Filter

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

Methods

(==) :: Filter -> Filter -> Bool

(/=) :: Filter -> Filter -> Bool

Show Filter

Methods

showsPrec :: Int -> Filter -> ShowS

show :: Filter -> String

showList :: [Filter] -> ShowS

type OptionMap = HashMap Text Text

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

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

passFilter :: Filter

A Filter that selects all tests in all suites.

allSelector :: Selector

A Selector that selects all tests.

combineSelectors :: Selector -> Selector -> Selector

Combine two Selectors into a single Selector.

suiteSelectors

Arguments

:: [Text]

The names of all test suites.

-> [Filter]

The list of Filters 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

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])

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

parseFilterFileContent

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.