ExpectMeta¶

ExpectMeta object implementation.

ExpectMeta.new¶

ExpectMeta.new(env, exprs=[], details=[], format_str_kwargs=None)

Creates a new “ExpectMeta” struct”.

Method: ExpectMeta.new

ExpectMeta objects are internal helpers for the Expect object and Subject objects. They are used for Subjects to store and communicate state through a series of call chains and asserts.

This constructor should only be directly called by Expect objects. When a parent Subject is creating a child-Subject, then [derive()] should be used.

Env objects¶

The env object basically provides a way to interact with things outside of the truth assertions framework. This allows easier testing of the framework itself and decouples it from a particular test framework (which makes it usable by by rules_testing’s analysis_test and skylib’s analysistest)

The env object requires the following attribute:

ctx: The test’s ctx.

The env object allows the following attributes to customize behavior:

fail: A callable that accepts a single string, which is the failure message. Its return value is ignored. This is called when an assertion fails. It’s generally expected that it records a failure instead of immediately failing.
has_provider: (callable) it accepts two positional args, target and provider and returns bool. This is used to implement Provider in target operations.
get_provider: (callable) it accepts two positional args, target and provider and returns the provider value. This is used to implement target[Provider].

PARAMETERS ¶

env¶:: unittest env struct or some approximation.
exprs¶:: (default []) (list of str) the expression strings of the call chain for the subject.
details¶:: (default []) (list of str) additional details to print on error. These are usually informative details of the objects under test.
format_str_kwargs¶:: (default None) optional dict of format() kwargs. These kwargs are propagated through derive() calls and used when ExpectMeta.format_str() is called.

RETURNS ¶: ExpectMeta object.

ExpectMeta.derive¶

ExpectMeta.derive(expr=None, details=None, format_str_kwargs={})

Create a derivation of the current meta object for a child-Subject.

Method: ExpectMeta.derive

When a Subject needs to create a child-Subject, it derives a new meta object to pass to the child. This separates the parent’s state from the child’s state and allows any failures generated by the child to include the context of the parent creator.

Example usage:

def _foo_subject_action_named(self, name):
    meta = self.meta.derive("action_named({})".format(name),
                            "action: {}".format(...))
    return ActionSubject(..., meta)
def _foo_subject_name(self):
    # No extra detail to include)
    meta self.meta.derive("name()", None)

PARAMETERS ¶

expr¶:: (default None) (str) human-friendly description of the call chain expression. e.g., if foo_subject.bar_named("baz") returns a child-subject, then “bar_named(“bar”)” would be the expression.
details¶:: (default None) (optional list of str) human-friendly descriptions of additional detail to include in errors. This is usually additional information the child Subject wouldn’t include itself. e.g. if foo.first_action_argv().contains(1), returned a ListSubject, then including “first action: Action FooCompile” helps add context to the error message. If there is no additional detail to include, pass None.
format_str_kwargs¶:: (default {}) (dict of format()-kwargs) additional kwargs to make available to format_str calls.

RETURNS ¶: ExpectMeta object.

ExpectMeta.format_str¶

ExpectMeta.format_str(template)

Interpolate contextual keywords into a string.

This uses the normal format() style (i.e. using {}). Keywords refer to parts of the call chain.

The particular keywords supported depend on the call chain. The following are always present: {workspace}: The name of the workspace, e.g. “rules_proto”. {test_name}: The base name of the current test.

PARAMETERS ¶

template¶:: (str) the format template string to use.

RETURNS ¶: str; the template with parameters replaced.

ExpectMeta.get_provider¶

ExpectMeta.get_provider(target, provider)

Get a provider from a target.

This is equivalent to target[provider]; the extra level of indirection is to aid testing.

PARAMETERS ¶

target¶:: (Target) the target to get the provider from.
provider¶:: The provider type to get.

RETURNS ¶: The found provider, or fails if not present.

ExpectMeta.has_provider¶

ExpectMeta.has_provider(target, provider)

Tells if a target has a provider.

This is equivalent to provider in target; the extra level of indirection is to aid testing.

PARAMETERS ¶

target¶:: (Target) the target to check for the provider.
provider¶:: the provider type to check for.

RETURNS ¶: True if the target has the provider, False if not.

ExpectMeta.add_failure¶

ExpectMeta.add_failure(problem, actual)

Adds a failure with context.

Method: ExpectMeta.add_failure

Adds the given error message. Context from the subject and prior call chains is automatically added.

PARAMETERS ¶

problem¶:: (str) a string describing the expected value or problem detected, and the expected values that weren’t satisfied. A colon should be used to separate the description from the values. The description should be brief and include the word “expected”, e.g. “expected: foo”, or “expected values missing: ”, the key point being the reader can easily take the values shown and look for it in the actual values displayed below it.
actual¶:: (str) a string describing the values observed. A colon should be used to separate the description from the observed values. The description should be brief and include the word “actual”, e.g., “actual: bar”. The values should include the actual, observed, values and pertinent information about them.

ExpectMeta.call_fail¶

ExpectMeta.call_fail(msg)

Adds a failure to the test run.

PARAMETERS ¶

msg¶:: (str) the failure message.