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: Optional[str] = None, param_meta: Optional[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
Optional[str]
- param_meta
If this is a parameterised test, contains info about the parameterisation.
- Type
Optional[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.
- 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