Package Generator API Reference¶

An overview of commands for Package generator.

Info

This API is included in the ecu.test Interface Python Library ecutest-interface.

PackageGenerator¶

class PackageGenerator¶

Base class for user-defined package generators.

Derive your generator from this class and implement the generation lifecycle. During execution, ecu.test instantiates your class, calls PreGeneration(), iterates over GenerationIterator(), and finally calls PostGeneration().

Typical workflow:

Set mandatory class attributes ID and NAME.
Optionally declare serializable instance attributes in SERIALIZE.
Build one CycleData per generated package via CreateCycleData().
Add package content to cycleData.packageInstance using cycleData.objectApi.
Yield each prepared cycleData from GenerationIterator().

Some fields and methods must be overridden (mandatory), others may be overridden (optional). Helper methods (without an override note) are intended to be called by your implementation and should not be overridden.

DESCRIPTION : str = ''¶: Short description of the package generator shown in the UI.

FORMAT_REV = 0¶

Format revision of persisted generator data.

Increase this only if your serialized data structure is intentionally incompatible with older revisions and you provide a migration strategy. Otherwise keep this value at 0.

ID : str = ''¶

Universally unique identifier of the package generator.

Use a UUID string and never change it after the generator is used in projects, because projects persist only this identifier.

Info

Setting this field is mandatory

NAME : str = ''¶: Display name of the package generator shown in the UI.

Info

Setting this field is mandatory

SERIALIZE : dict[str, tuple[str, str] | tuple[str, str, object]] = {}¶

Declaration of generator instance attributes that are persisted in project XML.

Add one dictionary item per instance attribute. Example:

SERIALIZE = {
    'foo': ('FOO-VAR', 'integer', 23),
    'bar': ('BAR', 'string'),
    'params': ('PARAMETERS', 'list'),
}

The declaration key must match the attribute name exactly (for example self.foo requires 'foo' as key). The value tuple must contain at least two elements:

``<variable name>: (<variable alias>, <type alias>, [default value])``

Syntax and meaning of the tuple’s elements are:

<variable alias> declares the name of the xml element that is used for the variable’s xml representation.
<type alias> keyword specifying the Python variable type:
- boolean: bool
- integer: int
- long: int
- float: float
- string: str
- unicode: str
- list: list
- dict: dict

Keys of serialized dictionaries must be strings. Values in lists and dictionaries (including nested structures) must be bool, int, float, str, list or dict. long and unicode are legacy compatibility aliases and should not be used in new code.

<default value> is an optional element. It specifies the variable’s default value. If the variable’s value equals its default value during export the variable is not exported at all. Conversely, the variable is assigned its default value during import if the XML data does not provide a value for the attribute.

api = None¶

Access to the internal ecu.test API.

This reference is assigned at runtime. Use it for settings or helper services from within the generator.

See also

Internal APIs

projectPath : str | None = None¶

Absolute path of the project file associated with the current run.

During direct execution this is the source project file. During static generation this is the destination project file.

classmethod GetDescription()¶

Returns the description of the package generator. The description can be specified by setting the class variable DESCRIPTION.

Returns:: Description text of the package generator.
Return type:: str

classmethod GetFormatRev()¶

Returns the format revision of the package generator. The format revision can be specified by setting the class variable FORMAT_REV. This is an optional parameter.

Returns:: Format revision number, or None if not defined.
Return type:: int | None

classmethod GetId()¶

Returns the universally unique identifier of the package generator. The identifier should be specified by setting the class variable ID.

Returns:: Unique identifier of the package generator.
Return type:: str

classmethod GetName()¶

Returns the name of the package generator. The name should be specified by setting the class variable NAME.

Returns:: Display name of the package generator.
Return type:: str

Check()¶

Validate the generator configuration.

Returns:: A list of error messages or an empty list if everything is fine.
Return type:: list[str]

Info

Overriding this method is optional

CreateCycleData(name=None, template=None)¶

Create a CycleData object for one generated package.

In ecu.test, this helper returns a runtime-specific cycle object. When template is given, its package is opened as the starting point; otherwise, ecu.test creates an empty package. Populate cycleData.packageInstance through cycleData.objectApi before yielding it.

Parameters:

name : str | None¶: Optional display name for this cycle in the report.
template : str | None¶: Optional path to a template package used as the package base.

Returns:

Cycle object that contains Object API access and package data for one run.

Return type:

CycleData

DryGenerationEnabled()¶

Return whether dry generation mode is active.

In dry generation mode, yielded cycles are converted to static package calls instead of being executed immediately.

Returns:: True if dry generation mode is active, otherwise False.
Return type:: bool

abstractmethod GenerationIterator()¶

Generate packages cycle by cycle.

This method must be an iterator that yields CycleData instances. Create each cycle via CreateCycleData(), fill cycleData.packageInstance and optionally append parameter sets, then yield cycleData.

Example:

def GenerationIterator(self):
    cycleData = self.CreateCycleData('GeneratedPackage')
    comment = cycleData.objectApi.PackageApi.TestStepApi.CreateTsComment('Generated')
    cycleData.packageInstance.AppendTestStep(comment)
    yield cycleData

During normal execution each yielded cycle is executed immediately. During static generation, each yielded cycle is exported to a package and inserted as a package call.

Info

Overriding this method is mandatory

GetDialog()¶

Return a configuration dialog for editing generator settings.

Use this dialog to edit instance attributes referenced by SERIALIZE.

Returns:: Configuration dialog instance, or None if no dialog is required.
Return type:: wx.Dialog | None

Info

Overriding this method is optional

GetParameterText()¶

Return a short one-line text representation of the current generator settings.

The returned text is displayed in the project properties column.

Returns:: parameter text
Return type:: str

Info

Overriding this method is optional

GetTargetItemCount()¶

Return the expected number of cycles for progress reporting.

This method can be called repeatedly while generation is running, so the value may be computed dynamically.

Returns:: Expected number of generated package cycles.
Return type:: int

PostGeneration()¶

Hook that runs after generation finished or failed.

This method is called even if an exception occurred in PreGeneration() or GenerationIterator(). It is not guaranteed to run when execution is aborted externally (for example manual abort or abort-on-error behavior).

Info

Overriding this method is optional

PreGeneration()¶

Hook that runs once before GenerationIterator() is consumed.

Use it for validation, setup, or preparing expensive resources.

Info

Overriding this method is optional

class CycleData¶

Container for one generated package cycle.

Create instances via PackageGenerator.CreateCycleData() in your generator. Fill packageInstance with test steps and then yield the instance from PackageGenerator.GenerationIterator().

Name¶

Return the name displayed for this cycle in the report.

Returns:: Cycle display name.

objectApi : ObjectApi | None = None¶

Object API used to create package content and test steps.

ecu.test assigns this attribute to cycles created through PackageGenerator.CreateCycleData(). It is not normally available on an interface CycleData instance constructed directly.

packageInstance : Package | None = None¶

Package instance to populate for this cycle.

ecu.test creates this instance empty or opens it from the template passed to PackageGenerator.CreateCycleData(). Add or modify test steps before yielding the cycle.

AppendParameterSet(name)¶

Create and attach a parameter set for this generated package cycle.

Use this method when the generated package should run with multiple parameter sets. The returned Object API parameter-set object can be populated before the cycle is yielded. The runtime implementation validates that name is not empty.

Parameters:

name : str¶: Name of the parameter set that will be displayed in the report.

Returns:

Parameter set

Return type:

ParameterSet

GetName()¶

Return the name displayed for this cycle in the report.

Returns:: Cycle display name.
Return type:: str

GetParameterSets()¶

Return parameter sets attached to this cycle in their creation order.

The returned list is provided by ecu.test’s runtime cycle implementation. It is empty when AppendParameterSet() has not been called.

Returns:: Parameter sets currently attached to this cycle.
Return type:: list[ParameterSet]

SetName(value)¶

Set the name displayed for this cycle in the report.

ReferenceTestPackageGenerator¶

class ReferenceTestPackageGeneratorTools¶

This class provides convenience methods that can be used within the user code section of the Reference Test Package Generator.

An instance of this class is globally available as variable ‘tools’

static AppendTraceAnalysisReference(traceAnalysis, analysisReference, refName, testName)¶

Adds analysis reference trace step to the current trace analysis. The created ApiClient.TraceAnalysisReference. object is returned.

Parameters:

traceAnalysis¶: the current reference test trace analysis object
analysisReference : string¶: name of the episode
refName : string¶: name of the reference signal
testName : string¶: name of the test signal

Returns:

object of the analysis reference trace step

Return type:

ApiClient.TraceAnalysisReference

static ApplyPattern(string, pattern, debug=False)¶

Reduces a string according to a wildcard pattern.

Pattern syntax:

( ) … denotes part of the string that is of interest

* … substitute for any string

? … substitute for any character

If the pattern does not match the string, the full string is returned as is.

Example:: string = 'Signal_XY', pattern = 'Signal_(*)', result: 'XY'

Parameters:

string : str¶: String that is to be reduced
pattern : str¶: Pattern that is to be applied to the string
debug=False¶: Set to True to create debug prints

Returns:

Reduced substring or full string, if pattern does not match

static EnablePlot(traceStep, plotName='', condition='SUCCESS')¶

Adds a plot to the given traceStep with all signals used by the traceStep.

Parameters:

traceStep¶: the traceStep for which the plot will be enabled
plotName : string, optional¶: name of the plot, defaults to ‘Signal plot’
condition='SUCCESS'¶: Condition that must be matched to create a plot. Possible parameter values are ‘ALWAYS’, ‘SUCCESS’, ‘INCONCLUSIVE’, ‘FAILED’ or ‘NEVER’. Defaults to ‘SUCCESS’.

static Filter(signalList, includeFilter, excludeFilter='')¶

Removes signals from a list according to certain criteria.

The filter syntax corresponds to the Filter syntax as described in the ecu.test User Documentation under “Handling > Filter”.

Parameters:

signalList¶

List with Signal objects that is to be reduced

includeFilter : str¶

Filter to include certain signals. An empty filter includes everything.

E.g.: "name = '*_important'" (this can also be abbreviated to "'*_important'")

excludeFilter : str¶

Filter to exclude certain signals. An empty filter excludes nothing.

E.g.: "device != 'Primary'"

Returns:

List of filtered Signal objects

static GetOrCreateEpisode(traceAnalysis, episodeName=None)¶

The episode with the specified name is returned. If no name is specified, the first episode is returned. If no episode (with the specified name) yet exists, a new episode will be created and appended to the traceAnalysis. The newly created ApiClient.Episode object is returned.

Parameters:

traceAnalysis¶: the current reference test trace analysis object
episodeName : string, optional¶: name of the episode

Returns:

object of the episode

Return type:

ApiClient.Episode

GetSynchronizationConfiguration(packageObject, signals)¶

Returns the synchronization configuration and recording groups for the specified package based on the provided signals. The returned objects can be used to synchronize reference and test traces before comparison.

Parameters:

packageObject¶: object of the generated reference test package (ApiClient.Package)
signals : list[tuple[Signal, Signal]]¶: list of tuples of refSignal and testSignal. One of those can be ‘None’ if no matching signal was found.

Returns:

tuple of synchronization configuration, reference recording group and test recording group

Return type:

tuple of ApiClient.SyncConfig, referenceRecordingGroup<ApiClient.RecordingGroup> and testRecordingGroup<ApiClient.RecordingGroup>

class Signal¶

Represents a single signal inside a trace file. Signals can be easily compared with other Signal objects. Signals can also be used as a set for bulk operations.

device¶

Returns:: device name within trace file
Return type:: string

name¶

Returns:: signal name
Return type:: string

type¶

Returns:: type of trace file (ref|test)
Return type:: string

CreateMappingItem()¶

Creates and returns a mapping item for this signal.

Returns:: Newly created mapping item facade.
Return type:: MappingItemFacade

GetGenericSignalName()¶

Returns the generic identifier used for this signal in generated packages.

Returns:: Valid Python identifier for the generic signal name.
Return type:: str

GetMappingItem()¶

Returns the cached mapping item created for this signal.

Returns:: Mapping item facade, or None if no mapping item was created yet.
Return type:: MappingItemFacade | None

GetMappingReferenceName(device=None)¶

Returns the mapping reference name used in the package mapping space.

Returns:: Mapping reference name for this signal.
Return type:: str

GetRecordingGroupName()¶

Returns the recording group name for this signal.

Returns:: Recording group name derived from signal type and device.
Return type:: str

GetSignalGroupName()¶

Returns the signal group name of this signal.

Returns:: signal group name
Return type:: string