COM API¶

This module contains the types for the COM-Application-Server. The main class is COMApplication which is instantiated with the Prog-ID ‘trace.check.Application’.

Sample usage:

>>> import win32com.client
>>> import time
>>> exampleWorkspace = r"C:\\Daten\\ExampleWorkspace"
>>> testPackage = r"C:\\Daten\\ExampleWorkspace\\Packages\\test.pkg"
>>> traceCheck = win32com.client.Dispatch('trace.check.Application')
>>> traceCheck.IsApplicationRunning()
False
>>> traceCheck.StartTimeout
90
>>> traceCheck.StartTimeout = 120  # Change timeout for application start
>>> traceCheck.RunApplication(exampleWorkspace)
>>> while not traceCheck.IsApplicationRunning():
...     time.sleep(0.1)
>>> traceCheck.GetVersion()
6.4.0.55478
>>> pkg = traceCheck.OpenPackage(testPackage)
>>> pkg is not None
True
>>> testEnv = traceCheck.GetTestEnvironment()
>>> execInfo = testEnv.ExecutePackage(testPackage)
>>> while execInfo.GetState() == "RUNNING":
...     time.sleep(0.1)
>>> execInfo.GetPackageResult()
'SUCCESS'
>>> execInfo.GetReportDb()
'C:\Daten\ExampleWorkspace\TestReports\test_2016-05-17_173443\test.trf'

More examples (C#, Excel) can be found in <installation directory>/Help/api/ExampleCOM.

COMApplication_TRC¶

class COMApplication_TRC¶

Caches¶

Returns the cache module.

Returns:

A COMCaches object.

Return type:

COMCaches

Packages¶

Returns a container object which gives access to all opened packages in COM-Application.

Returns:

The container object to access all opened packages.

Return type:

COMPackages

Projects¶

Returns a container object which gives access to all opened projects in COM-Application.

Returns:

The container object to access all opened packages.

Return type:

COMProjects

StartTimeout¶

Property to get or set the timeout for the application start in seconds. Defaults to 90s.

Type:

int|float

ClosePackage(filename)¶

Closes a Package (test case).

Parameters:

filename : str¶

The full path name of the Package to close (for example “C:WorkspacePackagesSubfolderPackage.pkg”) or a path name relative to the Packages directory of the current workspace (for example “SubfolderPackage.pkg”)

Returns:

True, if the package was closed, otherwise False.

Return type:

bool

CloseProject(filename)¶

Closes a project.

Parameters:

filename : str¶

The full path name of the project to close or a path name relative to the Packages directory of the current workspace

Returns:

True, if the project was closed, otherwise False.

Return type:

bool

Exit(timeout=60)¶

Exits the currently running instance of the application (Hard Exit). Prefer the method Quit instead.

Parameters:

timeout : int¶

Timeout in seconds before giving up to wait for application shutdown and raising an exception.

Returns:

True, if operation successful.

Return type:

bool

Raises:

COMException – if shutdown failed

GeneratePackageDocumentation(pkgPath, docPath, doasync=True)¶

Creates documentation file(s) for a package or all packages in a folder depending on the given path.

Parameters:

pkgPath : str¶

Path of either a package or a folder containing packages.

docPath : str¶

Path where the documentation files will be created.

doasync : bool¶

Mode of execution: asynchronous if True otherwise synchronous.

Returns:

Path of the generated (index) document if synchronous mode otherwise None.

Return type:

str

GetAnalysisEnvironment()¶

Returns the analysis environment.

Returns:

A COMAnalysisEnvironment object.

Return type:

COMAnalysisEnvironment

GetCaches()¶

Returns the cache module.

Returns:

A COMCaches object.

Return type:

COMCaches

GetCurrentTestConfiguration()¶

Returns a TestConfiguration object providing access to settings of the currently active test configuration file.

Returns:

TestConfiguration object

Return type:

COMTestConfiguration

GetInstallDir()¶

Returns the installation directory.

Returns:

the installation directory.

Return type:

str

GetKeywordCatalogModule()¶

Returns the keyword catalog module.

Returns:

A COMKeywordCatalog object.

Return type:

COMKeywordCatalog

GetLoadedPatches()¶

Queries the list of loaded patches of the COM-Application.

Returns:

list of loaded patches

Return type:

list<str>

GetObjectApiPythonPath()¶

Returns Python path for Object API.

Append it to the sys.path variable to import the Object API:

import sys
sys.path.append(ecutest.GetObjectApiPythonPath())
from ApiClient import ApiClient

This directory also contains the JAR of the Java client and the DLL of the .Net client.

Returns:

Directory for Python path of Object API.

Return type:

str

GetPackages()¶

Returns a container object which gives access to all opened packages in COM-Application.

Returns:

The container object to access all opened packages.

Return type:

COMPackages

GetProjects()¶

Returns a container object which gives access to all opened projects in COM-Application.

Returns:

The container object to access all opened packages.

Return type:

COMProjects

GetSetting(settingName)¶

Queries the COM-Application setting value by name. Possible setting names are: - configPath - errorLogFile - generatorPath - language - logFile - packagePath - reportPath - templatePath - parameterPath - traceStepPath - userPyModulesPath - utilityPath - workspacePath - offlineModelPath - offlineSgbdPath - offlineFiuPath - settingsPath

Parameters:

settingName : str¶

the setting name

Returns:

setting value or None if not defined

Return type:

str or None

GetTestEnvironment()¶

Returns the test environment.

Returns:

A COMTestEnvironment object.

Return type:

COMTestEnvironment

GetTestManagementModule()¶

Returns the test management module.

Returns:

A COMTestManagement object.

Return type:

COMTestManagement

GetVersion()¶

Queries the COM-Application version.

Returns:

Version string.

Return type:

str

HasActiveTasks()¶

Returns if any tasks are running or are queued.

Returns:

True, if any active task exists.

Return type:

bool

IconizeMainFrame(iconize)¶

Iconize/Restore the MainFrame Window

Parameters:

iconize : bool¶

True - minimize window, False - restore window

Returns:

True if success, otherwise False

Return type:

bool

IsApplicationRunning()¶

Check if the application process is running and ready to use.

Returns:

True if application is already running, otherwise False.

Return type:

bool

IsStarted()¶

Returns whether the currently selected test configuration and testbench configuration are started.

Returns:

True if configurations are started, else False

Return type:

bool

IsXmlRpcApiBusy()¶

(undocumented) Returns whether the underlying XMLRPC API is currently blocked by another call

Return type:

boolean

LoadGlobalMapping(filename, index=-1, reloadIfNecessary=False)¶

Loads a mapping file (*.xam) into the global mapping space.

Parameters:

filename : str¶

The full path name of the mapping file to load or a path name relative to the current workspace.

index : int¶

The priority-index of the mapping file. Index 0 is highest priority. (default is ‘-1’ for lowest priority)

reloadIfNecessary : bool¶

Reload the mapping file when it is already open. (default: False)

Returns:

True, if the mapping file was successfully loaded, otherwise False.

Return type:

bool

MaximizeMainFrame(maximize)¶

Maximize/Restore the MainFrame Window

Parameters:

maximize : bool¶

True - maximize window, False - restore window

Returns:

True if success, otherwise False

Return type:

bool

OpenPackage(filename)¶

Opens an existing Package (test case) in COM-Application. If the package to be opened is password protected an exception is raised.

Parameters:

filename : str¶

The full path name of the Package to open (for example “C:WorkspacePackagesSubfolderPackage.pkg”) or a path name relative to the Packages directory of the current workspace (for example “SubfolderPackage.pkg”)

Returns:

COMPackage, if the package is successfully opened, otherwise None.

Return type:

COMPackage

Raises:

COMException – if the package is password protected

OpenProject(filename, execInCurrentPkgDir=False, filterExpression='')¶

Opens an existing project in COM-Application.

Parameters:

filename : str¶

The full path name of the project to open or a path name relative to the Packages directory of the current workspace

execInCurrentPkgDir : bool¶

defines whether relative references in the project are resolved starting from the current workspaces package directory or from the project file location

filterExpression : str¶

a valid filter expression (see the main help document, section ‘Projects’)

Returns:

COMProject, if the project is successfully opened, otherwise None.

Return type:

COMProject

OpenTestConfiguration(filename)¶

Opens a test-configuration file (*.tcf).

Parameters:

filename : str¶

The full path name of the test-configuration file to open or a path name relative to the Configurations directory of the current workspace

Returns:

True, if the configuration was successfully opened, otherwise False.

Return type:

bool

Quit(timeout=60)¶

Exits the currently running instance of the application (Soft Exit).

Parameters:

timeout : int¶

Timeout in seconds before giving up to wait for application shutdown and raising an exception.

Returns:

True, if success.

Return type:

bool

Raises:

COMException – if shutdown failed

RunApplication(workspaceDir=None, localSettingsDir=None)¶

Runs the application process and allows to specify a workspace directory. All other COM-Application methods require a running application process.

Parameters:

workspaceDir : str or None¶

The full path name of the workspace directory. This directory must exist. If no sub directory .workspace with the corresponding settings files exists in this directory it will be created as well as the needed sub directories under the workspace directory. If the settings files exist the default directories are used like specified there. If in this case a needed directory doesn’t exist it will be created. If omitted (None) the default settings are used. In this case all default directories must exist in order to run the application process.

localSettingsDir : str or None¶

Absolute path specification to the directory in which the local user settings should be read from and stored in. If a directory is specified, it must exist. No new directory is created. In addition, no workspace selection dialog is displayed when ecu.test starts if this option is set.

Raises:

COMException – if the application is already running or the process startup failed

Start()¶

Starts up the currently loaded test configuration and testbench configuration files and returns a COMTestEnvironment object.

The test configuration can be changed by calling OpenTestConfiguration otherwise the last run configuration will be used.

Returns:

A COMTestEnvironment object.

Return type:

COMTestEnvironment

Raises:

COMException – if the configuration start was prohibited by error in user script.

Stop()¶

Stops up the currently loaded test configuration and testbench configuration files and returns a COMTestEnvironment object.

Returns:

A COMTestEnvironment object.

Return type:

COMTestEnvironment

UnloadGlobalMapping(filename, force=False)¶

Unloads a mapping file (*.xam) from the global mapping space.

Parameters:

filename : str¶

The full path name of the mapping file to unload or a path name relative to the current workspace.

force : bool¶

Ignore unsaved changes. (default: False)

Returns:

True, if the mapping file was successfully unloaded, otherwise False.

Return type:

bool

UpdateUserLibraries()¶

Update all user libraries. Only possible if neither a test nor the analysis is running.

Returns:

True if success, otherwise False

Return type:

bool

WaitForIdle(timeout=None)¶

Waits until the job count in the task manager reaches zero. With the timeout parameter you can specify the maximum waiting time in seconds.

Parameters:

timeout : float¶

Timeout in seconds

Returns:

True, if a job count of zero was reached within the timeout

Return type:

bool

COMAnalysisEnvironment¶

class COMAnalysisEnvironment¶

This class represents the currently started analysis environment. This environment supports operations to run analysis jobs.

ExecuteJob(jobFile, createReportDir=True)¶

Starts the execution of an analysis job.

Parameters:

jobFile : str¶

The full path name of the analysis job file.

createReportDir : bool¶

Flag that indicates whether a new report directory is created, or whether the report should be stored next to the job.

Returns:

A COMAnalysisExecutionInfo object.

Return type:

COMAnalysisExecutionInfo

GetAnalysisExecutionInfo()¶

Returns:

A COMAnalysisExecutionInfo object.

Return type:

COMAnalysisExecutionInfo

MergeJobReports(mainReportFilename, jobReports)¶

Merge reports of analysis job executions into a main report.

Parameters:

mainReportFilename : str¶

filename of main report

jobReports : list<str>¶

list of filenames to reports of analysis job executions

Returns:

True if merge was successful, else False

Return type:

bool

COMAnalysisExecutionInfo¶

class COMAnalysisExecutionInfo¶

This class offers operations to obtain information of the currently running analysis job.

Abort()¶

Aborts the current analysis job execution.

Returns:

True, if the abort succeeded. False, if the analysis job execution has already finished or aborted.

Return type:

bool

GetLogFolder()¶

Returns:

Folder where trace and log files of the currently executed analysis job are stored. Please note, each analysis job execution has got a separate log folder.

Return type:

str

GetReportDb()¶

Returns:

Path to report database of current (or most recent) analysis job execution.

Return type:

str

GetResult()¶

Returns the result of the analysis job execution. If the execution has not finished yet, the result equates the result at calling time.

Returns:

The current result. One of - NONE - SUCCESS - INCONCLUSIVE - FAILED - ERROR

Return type:

str

GetStartTime()¶

Returns the time where the analysis job execution has started.

Returns:

The analysis job starting time.

Return type:

str

GetState()¶

Returns the state of the current analysis job execution.

Returns:

The state of the current analysis job execution. One of - IDLE - RUNNING - ABORTED - FINISHED

Return type:

str

WaitForTestexecutionCompletion(timeout=None)¶

Waits until the current analysis job execution state will change to ABORTED or FINISHED. The timeout parameter specifies the maximum waiting time.

Returns:

The state of the current analysis job execution. One of - IDLE - RUNNING - ABORTED - FINISHED

Return type:

str

COMCache¶

class COMCache¶

This class offers access to a specific file cache.

Clear(force=False)¶

Remove all cache files of this category.

Parameters:

force : bool¶

Close already opend cache files. ATTENTION: Data objects that are used in ecu.test will be destroyed.

GetFiles()¶

Returns all cache files of this category.

Returns:

List of available cache files

Return type:

list<str>

Insert(filePath, dbChannel='')¶

Insert a database to the cache.

Parameters:

filePath : str¶

The file path of the database to be added to the cache

dbChannel : str¶

The optional database channel. Only needed by bus and service databases.

COMCaches¶

class COMCaches¶

This class offers access to the different files caches.

GetA2lCache()¶

Provides access to A2L cache files.

Returns:

Cache object

Return type:

COMCache

GetBusCache()¶

Provides access to bus cache files.

Returns:

Cache object

Return type:

COMCache

GetElfCache()¶

Provides access to ELF cache files.

Returns:

Cache object

Return type:

COMCache

GetModelCache()¶

Provides access to model cache files.

Returns:

Cache object

Return type:

COMCache

GetServiceCache()¶

Provides access to service cache files.

Returns:

Cache object

Return type:

COMCache

COMConstant¶

class COMConstant¶

This object gives access to the properties of a constant.

Description¶

returns the description of this constant.

Returns:

the description of this constant

Return type:

str

Name¶

returns the name of this constant.

Returns:

the name of this constant

Return type:

str

Value¶

returns the value of this constant as string.

Returns:

the value of this constant

Return type:

str

GetDescription()¶

returns the description of this constant.

Returns:

the description of this constant

Return type:

str

GetName()¶

returns the name of this constant.

Returns:

the name of this constant

Return type:

str

GetValue()¶

returns the value of this constant as string.

Returns:

the value of this constant

Return type:

str

COMConstants¶

class COMConstants¶

This object gives access to all global constants of the currently loaded test configuration.

Count¶

returns the number of constants.

Returns:

the number of constants.

Return type:

int

GetCount()¶

returns the number of constants.

Returns:

the number of constants.

Return type:

int

Item(idxOrName)¶

returns a specified constant. idxOrName can be either the name or an index. If an index is given then it should be between 0 and GetCount() - 1

Parameters:

idxOrName¶

The name of the constant or an index

Returns:

the constant.

Return type:

COMConstant

COMKeywordCatalog¶

class COMKeywordCatalog¶

This class offers access to the keyword catalog interface.

Connect()¶

Trys to establish a connection to the keyword catalog server defined in the workspace settings.

Returns:

The connection state: True if the connection has been established, else False.

Return type:

boolean

GetAvailableCatalogs()¶

Returns the names of the available catalogs of the current project.

Returns:

List of available catalog names

Return type:

list<str>

GetAvailableProjects()¶

Returns the available projects.

Returns:

List of available project names

Return type:

list<str>

GetAvailableVariants()¶

Returns the available variants.

Returns:

List of available variant names

Return type:

list<str>

GetCurrentCatalogName()¶

Returns the name of the loaded catalog or None, if no catalog has been loaded.

Returns:

Name of current catalog or None

Return type:

str

GetCurrentProject()¶

Returns the name of the current project or None, if no project has been configured.

Returns:

Current project name or None

Return type:

str

GetCurrentVariant()¶

Returns the name of the current variant or None, if no variant has been configured.

Returns:

Current variant name or None

Return type:

str

IsConnected()¶

Returns the connection state to the keyword catalog server.

Returns:

True, if the connection has already been established.

Return type:

boolean

LoadCatalog(catalogName)¶

Loads the referenced catalog.

Parameters:

catalogName : str¶

Name of the catalog.

Raises:

exception – If an invalid catalog name has been referenced.

SetProject(projectName)¶

Sets the referenced project.

Parameters:

projectName : str¶

Project name

Raises:

exception – If an invalid project name has been referenced.

SetVariant(variantName)¶

Sets the referenced variant.

Parameters:

variantName : str¶

Variant name

Raises:

exception – If an invalid variant name has been referenced.

COMPackage¶

class COMPackage¶

This object gives access to the properties of an opened package.

Description¶

returns the description of this package.

Returns:

the name of this package

Return type:

str

Filename¶

returns the full path of this package.

Returns:

the full path of this package

Return type:

str

Name¶

returns the name of this package.

Returns:

the name of this package

Return type:

str

Variables¶

Returns a container object which gives access to all variables of this package.

Returns:

The container object to access all variables.

Return type:

COMVariables

Check(recursive=None, fix=False)¶

Returns a list of the errors of the package (including all subpackages).

Every list element is a tuple containing:

• file path

• seriousness (‘Error’, ‘Warning’, ‘Note’ (or ‘Exception’ if applicable))

• error message

• line number

• step UUID

• id (optional)

• origin (optional)

• fixed state

id and origin are optional and may be None.

Parameters:

recursive : bool | None¶

Specifies if the package should be checked recursively.

fix : bool¶

Apply available fixes automatically and persist them if safe. Applying fixes is rejected for already changed open packages.

Returns:

Error list

Return type:

list<tuple>

CheckNG(recursive=None, fix=False)¶

Returns converted error descriptions into specific WarningsNG plugin JSON format.

• issues

  • description (link to package)

  • directory (package parent directory)

  • fileName (package name)

  • message (error message)

  • packageName (workspace subdirectory path of package)

  • severity (Error -> ‘ERROR’, Warning -> ‘HIGH’ or Note -> ‘NORMAL’)

• size (count of issues)

• _class

Parameters:

recursive : bool¶

Specifies if the package should be checked recursively.

fix : bool¶

Apply available fixes automatically and persist them if safe. Applying fixes is rejected for already changed open packages.

Returns:

error descriptions as issues in JSON format

Return type:

str

GetDescription()¶

returns the description of this package.

Returns:

the name of this package

Return type:

str

GetFilename()¶

returns the full path of this package.

Returns:

the full path of this package

Return type:

str

GetName()¶

returns the name of this package.

Returns:

the name of this package

Return type:

str

GetVariables()¶

Returns a container object which gives access to all variables of this package.

Returns:

The container object to access all variables.

Return type:

COMVariables

COMPackages¶

class COMPackages¶

This object gives access to all opened packages in COM-Application.

Count¶

returns the number of opened packages in COM-Application.

Returns:

the number of opened packages.

Return type:

int

GetCount()¶

returns the number of opened packages in COM-Application.

Returns:

the number of opened packages.

Return type:

int

Item(pkg)¶

returns a specified package. pkg can be either the full path or an index. If an index is given then it should be larger than 0 and lesser the number of packages opened. How many packages are currently open can be determined with GetCount

Parameters:

pkg¶

The full path or an index

Returns:

the package.

Return type:

COMPackage

COMProject¶

class COMProject¶

This object gives access to the properties of an opened project.

Filename¶

returns the full path of this project.

Returns:

the full path of this project

Return type:

str

Packages¶

returns a list of packages used in this project.

Returns:

list of packages

Return type:

str

Check(recursive=None)¶

Returns a list of the errors of the project.

Every list element is a tuple containing:

• file path

• seriousness (‘Error’, ‘Warning’, ‘Note’ (or ‘Exception’ if applicable))

• error message

• line number

• step UUID

• id (optional)

• origin (optional)

id and origin are optional and may be None.

Parameters:

recursive : bool | None¶

Specifies if the project should be checked recursively.

Returns:

Error list

Return type:

list<tuple>

CheckNG(recursive=None)¶

Returns converted error descriptions into specific WarningsNG plugin JSON format.

• issues

  • description (link to project)

  • directory (project parent directory)

  • fileName (project name)

  • message (error message)

  • packageName (workspace subdirectory path of project)

  • severity (Error -> ‘ERROR’, Warning -> ‘HIGH’ or Note -> ‘NORMAL’)

• size (count of issues)

• _class

Parameters:

recursive : bool¶

Specifies if the project should be checked recursively.

Returns:

error descriptions as issues in JSON format

Return type:

str

GetFilename()¶

returns the full path of this project.

Returns:

the full path of this project

Return type:

str

GetPackages()¶

returns a list of packages used in this project.

Returns:

list of packages

Return type:

str

COMProjects¶

class COMProjects¶

This object gives access to all opened projects in COM-Application.

Count¶

returns the number of opened projects in COM-Application.

Returns:

the number of opened projects.

Return type:

int

GetCount()¶

returns the number of opened projects in COM-Application.

Returns:

the number of opened projects.

Return type:

int

Item(prj)¶

returns a specified project. prj can be either the full path or an index. If an index is given then it should be larger than 0 and lesser than the number of projects opened. How many projects are currently open can be determined with GetCount

Parameters:

prj¶

The full path or an index

Returns:

the project.

Return type:

COMProject

COMTestbenchConfiguration¶

class COMTestbenchConfiguration¶

Represent the currently loaded testbench configuration file and provides methods for accessing the contained settings.

GetFilename()¶

returns the full path of this testbench configuration.

Returns:

the full path of this testbench configuration

Return type:

str

GetToolhostInfo()¶

Returns a list of lists containing url, version, revision and loaded patches of all connected toolhosts.

Returns:

List of toolhost information(url, version, revision and loaded patches) as list

Return type:

list<list>

COMTestConfiguration¶

class COMTestConfiguration¶

Represent the currently loaded test configuration file and provides methods for accessing the contained settings.

Filename¶

returns the full path of this test configuration.

Returns:

the full path of this configuration

Return type:

str

GlobalConstants¶

Returns a container object which gives access to all global constants of the currently loaded test configuration.

Returns:

The container object to access all global constants.

Return type:

COMConstants

GetFilename()¶

returns the full path of this test configuration.

Returns:

the full path of this configuration

Return type:

str

GetGlobalConstants()¶

Returns a container object which gives access to all global constants of the currently loaded test configuration.

Returns:

The container object to access all global constants.

Return type:

COMConstants

SetGlobalConstant(name, value)¶

Assign a value to a global constant. If the global constant does not exist it is created. This method requires a test configuration file to be loaded, otherwise an exception is thrown. The changed test configuration is saved instantly.

Parameters:

name : str¶

Name of the constant to be modified.

value : str¶

Value to be assigned. This must be a literal of a python data type, e.g. “1” (int literal) or “‘foo’” (string literal) or “[1, 2, 3]” (literal for a list with integer elements).

SetReportBaseFolder(path)¶

Change base folder for test reports. If the new base folder does not exist it is created. The changed test configuration is saved instantly.

Parameters:

path : str¶

Absolute or relative path to the new report base folder. If a relative path is passed the data directory is used as reference directory.

COMTestEnvironment¶

class COMTestEnvironment¶

This class represents the currently started test environment. The test environment supports operations to run packages (testcases) and projects.

ExecutePackage(pkgFile, runTraceAnalysis=True, runTest=True, paramValueDictAsList=None, recInfoDictAsList=None, parameterFiles=None, interactive=False, traceAnalysisMode=1)¶

Starts the execution of the specified package file. The package must be already opened with OpenPackage. If it is not opened a call of this function will raise an error.

Parameters:

pkgFile : str¶

The full path name of the Package to execute (for example “C:\Workspace\Packages\Subfolder\Package.pkg”) or a path name relative to the Packages directory of the current workspace (for example “Subfolder\Package.pkg”)

runTraceAnalysis : bool¶

specifies whether the trace analysis should be executed

runTest : bool¶

specifies whether the test should be executed

paramValueDictAsList : list<tuple>¶

A list with tuples (name, value) of length two for each parameter for the test and the trace analysis. Due to technical restrictions of the COM interface the parameter values must not contain dictionaries.

recInfoDictAsList : list<tuple>¶

This list with tuples (recording group name, recording info list) assigns traces to recording groups.

The entry ‘recording group name’ is a name of an existing recording group.

The entry ‘recording info list’ is a list of recording infos. A recording info is a list of tuples (key, value) which defines a dictionary with the following structure:

path: Either a trace file or a list of trace files. This must be given.

recordingName: The name of the recording, if it is necessary. For instance in a container file format for the unique identification.

recordingNumber: The number of the recording, if it is necessary. For instance in a container file format for the unique identification.

recordingType: The file type of the recording. If not given, an auto type detection is performed.

formatDetails: Format specific details. See the ‘Supported file formats’ section in the documentation.

parameterFiles : list<str>¶

List of pathes to *.ppd files containing parameters to be applied to the package.

interactive : bool¶

Specify if the package should be executed in the interactive mode

traceAnalysisMode : int¶

For internal use only

Returns:

A COMTestExecutionInfo object.

Return type:

COMTestExecutionInfo

Raises:

COMException – This exception is raised if the packages was not opened before. Or the format of the parameter values is wrong.

ExecuteProject(prjFile, autocloseProjectProgressPnl=False, executionMode=1, interactive=False)¶

Starts the execution of the specified project file. The project must be already opened with OpenProject. If it is not opened a call of this function will raise an error.

Parameters:

prjFile : str¶

The full path name of the project file

autocloseProjectProgressPnl : bool¶

Determines whether the progress dialog will be closed when finished (default False).

executionMode : int¶

Specifies whether and how the analysis jobs should be executed.

0. no job execution

1. sequential job execution (default)

2. parallel job execution

5. sequential job execution without report merge of analysis job sub reports into the main test report

6. parallel job execution without report merge of analysis job sub reports into the main test report

9. job execution without running the test case part

interactive : bool¶

Specify if the project should be executed in the interactive mode

Returns:

A COMTestExecutionInfo object.

Return type:

COMTestExecutionInfo

Raises:

COMException – Will be raised if the project has not been opened.

ExecuteProjectArchive(przFile, autocloseProjectProgressPnl=True, executionMode=1, interactive=False)¶

Extracts a project archive and starts the execution of the archived project.

Parameters:

przFile : str¶

The full path name of the project archive file

autocloseProjectProgressPnl : boolean¶

Determines whether the progress dialog will be closed when finished (default False).

executionMode : int¶

Specifies whether and how the analysis jobs should be executed.

0. no job execution

1. sequential job execution (default)

2. parallel job execution

5. sequential job execution without report merge of analysis job sub reports into the main test report

6. parallel job execution without report merge of analysis job sub reports into the main test report

9. job execution without running the test case part

interactive : bool¶

Specify if the project should be executed in the interactive mode

Returns:

A COMTestExecutionInfo object.

Return type:

COMTestExecutionInfo

Raises:

COMException – Will be raised if the project archive could not be extracted or started.

GenerateTestReportDocument(reportFile, outDir, fmtConfigFile, waitUntilFinished=False)¶

Generates a handler based testreport on the filesystem. It uses the settings previously stored next to the trf. This is performed when the “Save settings for later generation next to the TRF” option of the report generator configuration is ticked.

Parameters:

reportFile : str¶

path to the TRF or PRF

outDir : str¶

output directory

fmtConfigFile : str¶

Path to the reportFormatFile(XML) specifying the generator settings which should be used.

waitUntilFinished : bool¶

defines whether the API call should block until generation is finished.

Returns:

always True

Return type:

bool

GenerateTestReportDocumentFromDB(dbFile, outDir, fmtName=None, waitUntilFinished=False, fmtConfig=None)¶

Generates a handler based testreport on the filesystem.

Parameters:

dbFile : str¶

path to the databasefile

outDir : str¶

output directory

fmtName : str¶

Name of the reportformat or handler which should be used. (Optional) The default is the standardhandler.

fmtConfig : list<tuples>¶

A list with tuples (name, value) of length two for each configuration parameter for the report format. Due to technical restrictions of the COM interface the parameter values must not contain dictionaries.

waitUntilFinished : bool¶

defines whether the API call should block until generation is finished.

Returns:

always True

Return type:

bool

GetTestExecutionInfo()¶

Returns:

A COMTestExecutionInfo object.

Return type:

COMTestExecutionInfo

COMTestExecutionInfo¶

class COMTestExecutionInfo¶

This class offers operations to obtain information of the currently running test.

TestReport¶

Get a new testreport object.

Abort()¶

Aborts the current testexecution.

Returns:

True, if the abort succeeded. False, if the testexecution has already finished or aborted.

Return type:

bool

AbortAfterCurrentProjectStep(timeout=None)¶

Aborts the current testexecution.

Returns:

True, if the abort succeded. False, if the testexecution has already finished or aborted.

Return type:

bool

GenerateTestReportDocument(outDir, fmtName=None, waitUntilFinished=False, fmtConfig=None)¶

Generates a handler based testreport on the filesystem.

Returns:

True - all o.k., otherwise False

Return type:

bool

Parameters:

outDir : str¶

output directory

fmtName : str¶

Name of the reportformat or handler which should be used (Optional). The default is the standardhandler.

waitUntilFinished : bool¶

defines whether the API call should block until generation is finished

fmtConfig : list(tuple(string, string))¶

A list with tuples (name, value) of length two for each configuration parameter for the reportformat, where name and value are of data type string (e.g., “True” instead of True for value). Due to technical restrictions of the COM interface the parameter values must not contain dictionaries.

Returns:

always True

Return type:

bool

GetLogFolder()¶

Returns:

Folder where trace and log files of the currently executed package are stored. If there is no test execution in progress the log folder of the most recent package run is returned. Please note, each package run has got a separate log folder.

Return type:

str

Raises:

COMException – Raises Exception when using this method on project executions.

GetPackageAbortCode()¶

Returns the abort code of the most recently executed package.

Return type:

str

GetPackageAbortComment()¶

Returns the abort comment of the most recently executed package.

Return type:

str

GetReportDb()¶

Returns:

Path to report database of current (or most recent) test run.

Return type:

str

GetResult()¶

Returns the result of the project execution or package execution, depending on which method (COMTestEnvironment.ExecuteProject() or COMTestEnvironment.ExecutePackage()) has called before. If the testexecution has not finished yet, the result equates the testresult at calling time.

Returns:

The current overall testresult. One of - NONE - SUCCESS - INCONCLUSIVE - FAILED - ERROR

Return type:

str

GetReturnValue(varName)¶

If a test execution has finished GetReturnValue returns the final value of a package variable.

Parameters:

varName : str¶

the variable name

Returns:

the final variable value

Return type:

dynamic

GetStartTime()¶

Returns the time where the testexecution starts.

Returns:

The testexecution starting time.

Return type:

str

GetState()¶

Returns the state of the current testexecution.

Returns:

The state of the current testexecution. One of - IDLE - RUNNING - ABORTED - FINISHED

Return type:

str

GetTestReport()¶

returns the test report of the current or most recent testrun

Returns:

the test report of the current or most recent testrun

Return type:

COMTestReport

WaitForTestexecutionCompletion(timeout=None)¶

Waits until the current testexecution state will change to ABORTED or FINISHED. With the timeout parameter you can specify the maximum waiting time.

Returns:

The state of the current testexecution. One of - IDLE - RUNNING - ABORTED - FINISHED

Return type:

str

COMTestManagement¶

class COMTestManagement¶

This class offers access to the test management interface.

These methods can only be used if access to a test management system has previously been configured (once) manually for the current workspace.

ExportPackage(filePath, exportPath, createNewPath=False, overrideExisting=True, timeout=None)¶

Exports the given package into the test management system. The exportPath is needed to specify where the package should be placed at.

Parameters:

filePath : str¶

The file path of the package to be exported (relative to package directory or absolute).

exportPath : str¶

Path specifying where the project should be placed at. Specify the path as it would be displayed in the export dialog. Only Unix styled paths (separated by forward slashes, “/”) are allowed.

createNewPath : bool¶

If the exportPath does not exist, it will be created. (Optional) The default is False.

overrideExisting : bool¶

Defines, if an existing package with the same name (in the referenced folder) should be overridden.

timeout : int¶

timeout in seconds to wait for export to be finished (optional).

Raises:

exception – If a user adapter is currently active. Or the test management system is not configured. Or the user is not authenticated.

ExportPackageAttributes(filePath, timeout=None)¶

Exports the attributes of the given package to test management system.

Parameters:

filePath : str¶

The file path of the package whose attributes have to be exported (relative to package directory or absolute).

timeout : int¶

timeout in seconds to wait for import to be finished (optional).

Raises:

exception – If a user adapter is currently active. Or the test management system is not configured. Or the user is not authenticated.

ExportPackageChanges(filePath, timeout=None)¶

Exports the changes of the given package into the test management system. The package needs to be already link with the test management system.

Parameters:

filePath : str¶

The file path of the package to be exported (relative to package directory or absolute).

timeout : int¶

timeout in seconds to wait for export to be finished (optional).

Raises:

exception – If a user adapter is currently active. Or the test management system is not configured. Or the user is not authenticated.

ExportProject(filePath, exportPath, createNewPath=False, overrideExisting=True, timeout=None)¶

Exports the given project into the test management system. The exportPath is needed to specify where the project should be placed at.

Parameters:

filePath : str¶

The filepath of the project to be exported (relative to package directory or absolute).

exportPath : str¶

Path specifying where the project should be placed at. Specify the path as it would be displayed in the export dialog. Only Unix styled paths (separated by forward slashes, “/”) are allowed.

createNewPath : bool¶

If the exportPath does not exist, it will be created. (Optional) The default is False.

overrideExisting : bool¶

Defines, if an existing project with the same name (in the referenced folder) should be overridden.

timeout : int¶

timeout in seconds to wait for the export to be finished (optional).

Raises:

exception – If a user adapter is currently active. Or the test management system is not configured. Or the user is not authenticated.

ExportProjectAttributes(filePath, timeout=None)¶

Exports the attributes of the given project to test management system.

Parameters:

filePath : str¶

The file path of the project whose attributes have to be exported (relative to package directory or absolute).

timeout : int¶

timeout in seconds to wait for import to be finished (optional).

Raises:

exception – If a user adapter is currently active. Or the test management system is not configured. Or the user is not authenticated.

ExportReport(filePath, archivePath=None, timeout=None)¶

Exports the given project report file into the test management system. The archive path may be used to copy the report to another directory and to reference it from the test management entry.

Parameters:

filePath : str¶

The filepath of the project report file to be exported

archivePath : str¶

Path to directory or filename to copy the report to and to reference in test management (optional).

timeout : int¶

timeout in seconds to wait for the export to be finished (optional).

Raises:

exception – If a user adapter is currently active. Or the test management system is not configured. Or the user is not authenticated.

GetActiveConfigurationName()¶

Returns the name of the currently loaded test management configuration.

Returns:

name of test managemnt configuration

Return type:

str

GetConfigurationNames()¶

Returns a list of all configuration names defined in the settings.

Returns:

list of configuration names

Return type:

list<str>

ImportPackage(tmPackagePath, importPath, timeout=None)¶

Imports a package from a test management system. The tmPackagePath specifies the package in the test management system. The package will be imported into the directory given by importPath.

Parameters:

tmPackagePath : str¶

Path specifying the package in the test management system, as it would be displayed in the import dialog. Only Unix styled paths (separated by forward slashes, “/”) are allowed.

importPath : str¶

Directory, where the package should be placed (relative to package directory or absolute).

timeout : int¶

timeout in seconds to wait for the import to be finished (optional).

Raises:

exception – If a user adapter is currently active. Or the test management system is not configured. Or the user is not authenticated.

ImportPackageAttributes(filePath, timeout=None)¶

Imports the attributes of a package from the test management system. The package must exist within the local workspace or an exception will be raised.

Parameters:

filePath : str¶

The file path of the package whose attributes have to be imported

timeout : int¶

timeout in seconds to wait for import to be finished (optional).

Raises:

exception – If a user adapter is currently active. Or the test management system is not configured. Or the user is not authenticated.

ImportPackageById(tmPackageId, importPath, timeout=None)¶

Imports a package from a test management system. The tmPackageId specifies the package in the test management system. The package will be imported into the directory given by importPath.

Parameters:

tmPackageId : str¶

Id specifying the package in the test management system, as it would be displayed in the import dialog.

importPath : str¶

Directory, where the package should be placed (relative to package directory or absolute).

timeout : int¶

timeout in seconds to wait for the import to be finished (optional).

Raises:

exception – If a user adapter is currently active. Or the test management system is not configured. Or the user is not authenticated.

ImportPackageDirectory(tmDirectoryPath, importPath, timeout=None)¶

Imports a directory from a test management system with all subdirectories and packages. The tmDirectoryPath specifies the directory in the test management system. The directory will be imported into the directory given by importPath.

Parameters:

tmDirectoryPath : str¶

Path specifying the directory in the test management system, as it would be displayed in the import dialog. Only Unix styled paths (separated by forward slashes, “/”) are allowed.

importPath : str¶

Directory, where the imported directory should be placed (relative to package directory or absolute).

timeout : int¶

timeout in seconds to wait for import to be finished (optional).

Raises:

exception – If a user adapter is currently active. Or the test management system is not configured. Or the user is not authenticated.

ImportProject(tmProjectPath, importPath, importMissingPackages=False, timeout=None, parameters=None)¶

Imports a project from a test management system. The tmProjectPath specifies the project in the test management system. The project will be imported into the directory given by importPath.

Parameters:

tmProjectPath : str¶

Path specifying the project in the test management system, as it would be displayed in the import dialog. Only Unix styled paths (separated by forward slashes, “/”) are allowed.

importPath : str¶

Directory, where the project should be placed (relative to package directory or absolute).

importMissingPackages : bool¶

If set, missing packages will be automatically imported.

timeout : int¶

timeout in seconds to wait for the import to be finished (optional).

parameters : list<tuple>¶

A list of tuples (name, value) of length two for each adapter parameter to be temporarily changed for the duration of the project import. Due to technical restrictions of the COM interface the parameter values must not contain dictionaries.Following adapter parameters can be set: Suite Run Query (only ALM Octane), Test Suite Query (only ALM Octane)

Raises:

exception – If a user adapter is currently active. Or the test management system is not configured. Or the user is not authenticated.

ImportProjectAttributes(filePath, timeout=None)¶

Imports the attributes of a project from the test management system. The project must exist within the local workspace or an exception will be raised.

Parameters:

filePath : str¶

The file path of the project whose attributes have to be imported

timeout : int¶

timeout in seconds to wait for import to be finished (optional).

Raises:

exception – If a user adapter is currently active. Or the test management system is not configured. Or the user is not authenticated.

ImportProjectById(tmProjectId, importPath, importMissingPackages=False, timeout=None)¶

Imports a project from a test management system. The tmProjectId specifies the project in the test management system. The project will be imported into the directory given by importPath.

Parameters:

tmProjectId : str¶

Id specifying the project in the test management system, as it would be displayed in the import dialog.

importPath : str¶

Directory, where the project should be placed (relative to package directory or absolute).

importMissingPackages : bool¶

If set, missing packages will be automatically imported.

timeout : int¶

timeout in seconds to wait for the import to be finished (optional).

Raises:

exception – If a user adapter is currently active. Or the test management system is not configured. Or the user is not authenticated.

ImportProjectDirectory(tmDirectoryPath, importPath, timeout=None, parameters=None)¶

Imports a directory from a test management system with all subdirectories and projects. The tmDirectoryPath specifies the directory in the test management system. The directory will be imported into the directory given by importPath.

Parameters:

tmDirectoryPath : str¶

Path specifying the directory in the test management system, as it would be displayed in the import dialog. Only Unix styled paths (separated by forward slashes, “/”) are allowed.

importPath : str¶

Directory, where the imported directory should be placed (relative to package directory or absolute).

timeout : int¶

timeout in seconds to wait for import to be finished (optional).

parameters : list<tuple>¶

A list of tuples (name, value) of length two for each adapter parameter to be temporarily changed for the duration of the project import. Due to technical restrictions of the COM interface the parameter values must not contain dictionaries. Following adapter parameters can be set: Suite Run Query (only ALM Octane), Test Suite Query (only ALM Octane)

Raises:

exception – If a user adapter is currently active. Or the test management system is not configured. Or the user is not authenticated.

IsLoggedIn()¶

Returns True if ecu.test is currently logged in the Testmanagement system, else False

Returns:

True if ecu.test is currently logged in the Testmanagement system, else False

Return type:

bool

Raises:

exception – If a user adapter is currently active.

IsTmsAvailable()¶

Checks if the test management service is available.

Returns:

True if the service is available, otherwise False.

Return type:

bool

LinkAndSyncProject(filePath, tmProjectPath)¶

Links a project from ecu.test with a test suite in the test management system and synchronizes the contained test cases.

Parameters:

filePath : str¶

The file path of the project to be linked and synced (relative to package directory or absolute).

tmProjectPath : str¶

Path specifying the project in the test management system, as it would be displayed in the import dialog. Only Unix styled paths (separated by forward slashes, “/”) are allowed.

Returns:

Empty list on success, otherwise a list of messages from unsynced test cases.

Return type:

list<string>

Raises:

exception – If a user adapter is currently active. Or the test management system is not configured. Or the user is not authenticated.

Login(user, password)¶

Performs a login to the preconfigured test management service.

Info

Will try a “Basic” Authentication regardless of the configuration.

Parameters:

user : str¶

User to be logged in

password : str¶

Password of the user

Returns:

True if login succeeded, else False

Return type:

bool

Raises:

exception – If a user adapter is currently active.

Logout()¶

Performs a logout from the preconfigured test management service.

Returns:

True if logout succeeded, else False

Return type:

bool

Raises:

exception – If a user adapter is currently active.

SetActiveConfiguration(configName)¶

Activate the specified test management configuration.

Parameters:

configName : str¶

Name of the test management configuration

UpdateAttributeDefinitions(timeout=None)¶

Updates the attribute definitions with attributes of the currently configured test management system.

Parameters:

timeout : int¶

timeout in seconds to wait for import to be finished (optional).

Raises:

exception – If a user adapter is currently active. Or the test management system is not configured. Or the user is not authenticated.

COMTestReport¶

class COMTestReport¶

This object gives access to the test report of the current or most recent testrun

Count¶

returns the number of items in this test report. If the package was not executed yet GetCount will return 0. See: IsOk

Returns:

the number of items.

Return type:

int

Activity(idx)¶

returns the test step’s activity of the item with the specified index.

Parameters:

idx : int¶

the index of the item to obtain the test step’s activity.

Returns:

the test step’s activity of the specified item

Return type:

str

Comment(idx)¶

returns the test step’s comment of the item with the specified index.

Parameters:

idx : int¶

the index of the item to obtain the comment.

Returns:

the comment of the specified item

Return type:

str

GetAnalysisJobFiles(extract=True)¶

Get absolute file paths to all analysis jobs within the report.

Info

The files may not be present anymore on the filesystem.

Parameters:

extract : bool¶

If true, extract the analysis job files into the report folder

Returns:

list of file paths

Return type:

list<str>

GetCount()¶

returns the number of items in this test report. If the package was not executed yet GetCount will return 0. See: IsOk

Returns:

the number of items.

Return type:

int

Index(idx)¶

returns the index of the item with the specified index.

Parameters:

idx : int¶

the index of the item to obtain the name.

Returns:

the name of the specified item

Return type:

str

Info(idx)¶

returns the info field’s value of the item with the specified index.

Parameters:

idx : int¶

the index of the item to obtain the info field.

Returns:

the info field’s value of the specified item

Return type:

str

IsOk()¶

This method can be used to check if this test report is valid or more precisely the package was already executed and a test report is available.

Returns:

True, if this test report is valid, otherwise False. It is a convenience function for:

GetCount() > 0

Return type:

bool

Item(idx)¶

See: Result

Name(idx)¶

returns the name of the item with the specified index.

Parameters:

idx : int¶

the index of the item to obtain the name.

Returns:

the name of the specified item

Return type:

str

Result(idx)¶

returns the result of the item with the specified index.

Parameters:

idx : int¶

the index of the item to obtain the result.

Returns:

the result of the specified item

Return type:

str

TimeStamp(idx)¶

returns the time stamp of the item with the specified index.

Parameters:

idx : int¶

the index of the item to obtain the time stamp.

Returns:

the time stamp of the specified item

Return type:

str

COMVariable¶

class COMVariable¶

This object gives access to the properties of a variable.

Description¶

returns the description of this variable.

Returns:

the description of this variable

Return type:

str

InitValue¶

returns the initial value of this variable as string.

Returns:

the initial value of this variable

Return type:

str

Name¶

returns the name of this variable.

Returns:

the name of this variable

Return type:

str

GetDescription()¶

returns the description of this variable.

Returns:

the description of this variable

Return type:

str

GetInitValue()¶

returns the initial value of this variable as string.

Returns:

the initial value of this variable

Return type:

str

GetName()¶

returns the name of this variable.

Returns:

the name of this variable

Return type:

str

IsInput()¶

Returns True if this variable is an input parameter, otherwise False.

Returns:

whether this variable is an input parameter or not

Return type:

bool

IsOutput()¶

Returns True if this variable is an ouput parameter, otherwise False.

Returns:

whether this variable is an output parameter or not

Return type:

bool

COMVariables¶

class COMVariables¶

This object gives access to all variable of a package in COM-Application.

Count¶

returns the number of variables.

Returns:

the number of variables.

Return type:

int

GetCount()¶

returns the number of variables.

Returns:

the number of variables.

Return type:

int

Item(idxOrName)¶

returns a specified variable. idxOrName can be either the name or an index. If an index is given then it should be larger than 0 and lesser the number of variables. The count of variables can be determined with GetCount

Parameters:

idxOrName¶

The name of the variable or an index

Returns:

the variable.

Return type:

COMVariable