tracetools_test.case module

Module for a tracing-specific unittest.TestCase extension.

class tracetools_test.case.TraceTestCase(*args, session_name_prefix: str, events_ros: List[str], package: str, nodes: List[str], base_path: str | None = None, events_kernel: List[str] = [], additional_actions: List[launch.Action] | None = None, namespace: str | None = None)

Bases: TestCase

TestCase extension for tests on a trace.

Sets up tracing, traces given nodes, and provides the resulting events for an extending class to test on. It also does some basic checks on the resulting trace.

If the TRACETOOLS_TEST_DEBUG environment variable is set (and non-empty), the resulting trace will not be removed after the test.

The assert*() functions are specifically in mixedCase to match the unittest functions.

ENV_VAR_DEBUG = 'TRACETOOLS_TEST_DEBUG'

are_events_ordered(events: List[tracetools_read.DictEvent]) → bool

Check that the events were generated in the expected order.

Parameters:

events – the events in the expected order

assertEventAfterTimestamp(event: tracetools_read.DictEvent, timestamp: int) → None

Check that the event happens after the given timestamp.

Parameters:

• event – the event to check

• timestamp – the reference timestamp

assertEventOrder(events: List[tracetools_read.DictEvent]) → None

Check that the events are ordered (from their timestamps).

Parameters:

events – the events in the expected order

assertEventsSet(event_names: List[str]) → None

Compare given event names to trace events names as sets.

Parameters:

event_names – the list of event names to compare to (as a set)

assertFieldEquals(event: tracetools_read.DictEvent, field_name: str, value: Any, msg: str | None = None) → None

Check the value of a field.

Parameters:

• event – the event

• field_name – the name of the field to check

• value – to value to compare the field value to

• msg – the message to display on failure

assertFieldType(event: tracetools_read.DictEvent, field_names: str | List[str], field_type: Type) → None

Check that the type of a field value corresponds to the given type.

Parameters:

• event – the event

• field_names – the name(s) of field(s) to check

• field_type – the expected field value type

assertMatchingField(initial_event: tracetools_read.DictEvent, field_name: str, matching_event_name: str | None = None, events: List[tracetools_read.DictEvent] | None = None, check_order: bool = True) → None

Check that the value of a field for a given event has a matching event that follows.

Parameters:

• initial_event – the first event, which is the origin of the common field value

• field_name – the name of the common field to check

• matching_event_name – the name of the event to check (or None to check all)

• events – the events to check (or None to check all in trace)

• check_order – whether to check that the matching event comes after the initial event

assertNumEventsEqual(events: List[tracetools_read.DictEvent], expected_number: int, msg: str | None = None) → None

Check number of events.

Parameters:

• events – the events to check

• expected_number – the expected number of events

• msg – the message to display on failure

assertNumEventsGreaterEqual(events: List[tracetools_read.DictEvent], min_expected_number: int, msg: str | None = None) → None

Check that the number of events is greater of equal.

Parameters:

• events – the events to check

• min_expected_number – the minimum expected number of events

• msg – the message to display on failure

assertProcessNamesExist(names: List[str]) → None

Check that the processes with the given names exist.

Parameters:

names – the node names to look for

assertStringFieldNotEmpty(event: tracetools_read.DictEvent, string_field_name: str) → None

Check that a string field is not empty.

Parameters:

• event – the event which has a string field

• string_field_name – the field name of the string field

assertValidHandle(event: tracetools_read.DictEvent, handle_field_names: str | List[str], *, can_be_null: bool = False) → None

Check that the handle associated to a field name is valid.

Parameters:

• event – the event which has a handle field

• handle_field_names – the handle field name(s) to check

• can_be_null – whether the handle can be null

assertValidPointer(event: tracetools_read.DictEvent, pointer_field_names: str | List[str], *, can_be_null: bool = False) → None

Check that the pointer associated to a field name is valid.

Parameters:

• event – the event which has a pointer field

• pointer_field_names – the pointer field name(s) to check

• can_be_null – whether the pointer can be null

assertValidQueueDepth(event: tracetools_read.DictEvent, queue_depth_field_name: str = 'queue_depth') → None

Check that the queue depth value is valid.

Parameters:

• event – the event with the queue depth field

• queue_depth_field_name – the field name for queue depth

assertValidStaticArray(event: tracetools_read.DictEvent, array_field_names: str | List[str], array_type: Type | None = None, array_length: int | None = None) → None

Check that the static array associated to a field name is valid.

Optionally check its length and the type of its elements.

Parameters:

• event – the event which has a static array field

• array_field_names – the static array field name(s) to check

• array_type – the expected type of elements in the array, or None

• array_length – the expected length of the array, or None

get_event_with_field_value_and_assert(field_name: str, field_values: Any, events: List[tracetools_read.DictEvent] | None = None, *, allow_multiple: bool = False) → tracetools_read.DictEvent

Assert that an event with the given field:value exists and return it.

Can expect to get >=1 matching event, but always returns the first matching one.

Parameters:

• field_name – the name of the field to check

• field_values – the value(s) of the field to check

• events – the events to check (or None to check all events)

• allow_multiple – whether to allow multiple event matches

Returns:

the (first) event with the given field:value pair

get_events_with_field_not_value(field_name: str, field_values: Any, events: List[tracetools_read.DictEvent] | None = None) → List[tracetools_read.DictEvent]

Get all events with the given field but not the value.

Parameters:

• field_name – the name of the field to check

• field_values – the value(s) of the field to check

• events – the events to check (or None to check all events)

Returns:

the events with the given field:value pair

get_events_with_field_value(field_name: str, field_values: Any, events: List[tracetools_read.DictEvent] | None = None) → List[tracetools_read.DictEvent]

Get all events with the given field:value.

Parameters:

• field_name – the name of the field to check

• field_values – the value(s) of the field to check

• events – the events to check (or None to check all events)

Returns:

the events with the given field:value pair

get_events_with_name(event_name: str, events: List[tracetools_read.DictEvent] | None = None) → List[tracetools_read.DictEvent]

Get all events with the given name.

Parameters:

• event_name – the event name

• events – the events to check (or None to check all events)

Returns:

the list of events with the given name

get_events_with_procname(procname: str, events: List[tracetools_read.DictEvent] | None = None) → List[tracetools_read.DictEvent]

Get all events with the given procname.

Note: the given procname value will be truncated to the same max length as the procname field.

Parameters:

• procname – the procname

• events – the events to check (or None to check all events)

Returns:

the events with the given procname

get_field(event: tracetools_read.DictEvent, field_name: str) → Any

Get field value; will fail test if not found.

Parameters:

• event – the event from which to get the value

• field_name – the field name

Returns:

the value

get_procname(event: tracetools_read.DictEvent) → str

Get procname.

Parameters:

event – the event

Returns:

the procname of the event

get_tid(event: tracetools_read.DictEvent) → str

Get TID.

Parameters:

event – the event

Returns:

the TID of the event

setUp()

Hook method for setting up the test fixture before exercising it.

tearDown()

Hook method for deconstructing the test fixture after testing it.