HUnit-Plus-0.3.0: A test framework building on HUnit.

Safe HaskellSafe-Inferred
LanguageHaskell2010

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]

Where at least one of the suite, path, or tags 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 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.

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 :: Map String 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 (Set String))

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.

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 :: !(Set String)

The test suites to which the Selector applies. The empty set actually means 'all suites'.

filterSelector :: !Selector

The Selector to apply.

Instances

combineTags :: Maybe (Set String) -> Maybe (Set String) -> Maybe (Set String) 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

:: [String]

The names of all test suites.

-> [Filter]

The list of Filters from which to build the map.

-> Map String Selector 

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

parseFilter Source

Arguments

:: String

The name of the source.

-> String

The input.

-> Either String Filter 

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

parseFilterFile :: FilePath -> IO (Either [String] [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.

-> String

The file content.

-> Either [String] [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.