ward.testing

Standard API

ward.testing.skip(func_or_reason: Optional[Union[str, Callable]] = None, *, reason: Optional[str] = None, when: Union[bool, Callable] = True)

Decorator which can be used to optionally skip tests.

Parameters
  • func_or_reason (object) – The wrapped test function to skip.

  • reason – The reason the test was skipped. May appear in output.

  • when – Predicate function. Will be called immediately before the test is executed. If it evaluates to True, the test will be skipped. Otherwise the test will run as normal.

ward.testing.test(description: str, *args, tags: Optional[List[str]] = None, **kwargs)

Decorator used to indicate that the function it wraps should be collected by Ward.

Parameters
  • description – The description of the test. A format string. Resolve fixtures and default params that are injected into the test will also be injected into this description before it gets output in the test report. The description can contain basic Markdown syntax (bold, italic, backticks for code, etc.).

  • tags – An optional list of strings that will ‘tag’ the test. Many tests can share the same tag, and these tags can be used to group tests in some logical manner (for example: by business domain or test type). Tagged tests can be queried using the –tags option.

ward.testing.xfail(func_or_reason: Optional[Union[str, Callable]] = None, *, reason: Optional[str] = None, when: Union[bool, Callable] = True)

Decorator that can be used to mark a test as “expected to fail”.

Parameters
  • func_or_reason – The wrapped test function to mark as an expected failure.

  • reason – The reason we expect the test to fail. May appear in output.

  • when – Predicate function. Will be called immediately before the test is executed. If it evaluates to True, the test will be marked as an expected failure. Otherwise the test will run as normal.

Plugin API

This section contains items from this module that are intended for use by plugin authors or those contributing to Ward itself. If you’re just using Ward to write your tests, this section isn’t relevant.

class ward.testing.Test(fn: Callable, module_name: str, id: str = <factory>, marker: Optional[ward.models.Marker] = None, description: str = '', param_meta: ward.testing.ParamMeta = <factory>, capture_output: bool = True, sout: _io.StringIO = <factory>, serr: _io.StringIO = <factory>, ward_meta: ward.models.CollectionMetadata = <factory>, timer: Optional[ward._testing._Timer] = None, tags: List[str] = <factory>)

Representation of a test case.

fn

The Python function object that contains the test code.

Type

Callable

module_name

The name of the module the test is defined in.

Type

str

id

A unique UUID4 used to identify the test.

Type

str

marker

Attached by the skip and xfail decorators.

Type

Optional[ward.models.Marker]

description

The description of the test. A format string that can contain basic Markdown syntax.

Type

str

param_meta

If this is a parameterised test, contains info about the parameterisation.

Type

ward.testing.ParamMeta

capture_output

If True, output will be captured for this test.

Type

bool

sout

Buffer that fills with captured stdout as the test executes.

Type

_io.StringIO

serr

Buffer that fills with captured stderr as the test executes.

Type

_io.StringIO

ward_meta

Metadata that was attached to the raw functions collected by Ward’s decorators.

Type

ward.models.CollectionMetadata

timer

Timing information about the test.

Type

Optional[ward._testing._Timer]

tags

List of tags associated with the test.

Type

List[str]

find_number_of_instances()int

Returns the number of instances that would be generated for the current parameterised test.

A parameterised test is only valid if every instance of each contains an equal number of items. If the current test is an invalid parameterisation, then a ParameterisationError is raised.

format_description(args: Dict[str, Any])str

Applies any necessary string formatting to the description, given a dictionary args of values that will be injected into the test.

This method will mutate the Test by updating the description. Returns the newly updated description.

get_parameterised_instances()List[ward.testing.Test]

If the test is parameterised, return a list of Test objects representing each test generated as a result of the parameterisation. If the test is not parameterised, return a list containing only the test itself. If the test is parameterised incorrectly, for example the number of items don’t match across occurrences of each in the test signature, then a ParameterisationError is raised.

property is_async_test: bool

True if the test is defined with ‘async def’.

property is_parameterised: bool

True if a test is parameterised, False otherwise. A test is considered parameterised if any of its default arguments have a value that is an instance of Each.

property line_number: int

The line number the test is defined on. Corresponds to the line the first decorator wrapping the test appears on.

property name: str

The name of the Python function representing the test.

property path: pathlib.Path

The pathlib.Path to the test module.

property qualified_name: str

{module_name}.{test_function_name}

class ward.testing.TestOutcome(value)

Enumeration representing all possible outcomes of an attempt at running a test.

PASS

Represents a passing test outcome - no errors raised, no assertions failed, the test ran to completion.

FAIL

The test failed in some way - e.g. an assertion failed or an exception was raised.

SKIP

The test was skipped.

XFAIL

The test was expected to fail, and it did fail.

XPASS

The test was expected to fail, however it unexpectedly passed.

DRYRUN

The test was not executed because the test session was a dry-run.

class ward.testing.TestResult(test: ward.testing.Test, outcome: ward.testing.TestOutcome, error: Optional[Exception] = None, message: str = '', captured_stdout: str = '', captured_stderr: str = '')

Represents the result of a single test, and contains data that may have been generated as part of the execution of that test (for example captured stdout and exceptions that were raised).

test

The test corresponding to this result.

Type

ward.testing.Test

outcome

The outcome of the test: did it pass, fail, get skipped, etc.

Type

ward.testing.TestOutcome

error

If an exception was raised during test execution, it is stored here.

Type

Optional[Exception]

message

An arbitrary message that can be associated with the result. Generally empty.

Type

str

captured_stdout

A string containing anything that was written to stdout during the execution of the test.

Type

str

captured_stderr

A string containing anything that was written to stderr during the execution of the test.

Type

str