AdvancedUsage.md

Advanced Usage Documentation

This advanced usage documentation will provide the full specs of all steps implemented in the ecu.test execution plugin. Additionally, further examples are provided.

Step-Name	Parameters	Return
ttCheckPackage	testCasePath: String - The path to the file that should be checked. Can be package or project executionConfig: ExecutionConfig - Contains settings to handle ecu.test executions	CheckPackageResult
ttGenerateReports	generatorName: String - The name of the report generator to trigger, currently ATX, EXCEL, HTML, JSON, TRF-SPLIT, TXT and UNIT are supported additionalSettings: List<AdditionalSetting> - Additional settings for the chosen report generator. reportIds: List<String> - reportIds to generate a report for, ignore to generate all.	List<GenerationResult>
ttProvideLogs	publishConfig: PublishConfig - Contains settings to adjust how logs will be provided	/
ttProvideReports	publishConfig: PublishConfig - Contains settings to adjust how reports will be provided	/
ttProvideGeneratedReports	selectedReportTypes: String - Comma seperated names of generated report folders that should be included. publishConfig: PublishConfig - Contains settings to adjust how reports will be provided	/
ttRunPackage	testCasePath: String - The path to the package file that should be started. A test case file can be a package, project, project archive or analysis job. The path must either be an absolute path or a relative path to the Packages directory in the workspace. testConfig: TestConfig - Contains settings for the ecu.test configuration. executionConfig: ExecutionConfig - Contains settings to handle ecu.test executions packageConfig: PackageConfig - Contains package parameters analysisConfig: AnalysisConfig - Contains settings for analysis execution.	TestResult
ttRunProject	testCasePath: String - The path to the project file that should be started. A test case file can be a package, project, project archive or analysis job. The path must either be an absolute path or a relative path to the Packages directory in the workspace. testConfig: TestConfig - Contains settings for the ecu.test configuration. executionConfig: ExecutionConfig - Contains settings to handle ecu.test executions	TestResult
ttRunTestFolder	testCasePath: String - Absolute test folder path where packages/projects are located. testConfig: TestConfig - Contains settings for the ecu.test configuration. executionConfig: ExecutionConfig - Contains settings to handle ecu.test executions scanMode: ScanMode - Defines what types of files should be run (PACKAGES_ONLY, PROJECTS_ONLY, PACKAGES_AND_PROJECTS) failFast: boolean - The first failed package or project execution will abort the test folder execution immediately. packageConfig: PackageConfig - Contains package parameters analysisConfig: AnalysisConfig - Contains settings for analysis execution.	List<TestResult>
ttStartTool	toolName: String - Select a preconfigured ecu.test or trace.check installation workspaceDir: String - ecu.test or trace.check workspace, relative to build workspace or absolute path. settingsDir: String - ecu.test or trace.check settings directory, relative to build workspace or absolute path. timeout: int - Maximum time in seconds starting and connecting to the selected tool. keepInstance: boolean - Re-uses an already running ecu.test or trace.check instance with the currently loaded workspace instead of starting a new one. stopUndefinedTools: boolean - It only has an impact if Keep Previous Instance is unselected. Additionally, all tracetronic tools that are not defined by the Jenkins ETInstallations are stopped.	/
ttStopTool	toolName: String - Select a preconfigured ecu.test or trace.check installation timeout: int - Maximum time in seconds terminating the selected tool. stopUndefinedTools: boolean - Additionally, all tracetronic tools that are not defined by the Jenkins ETInstallations are stopped.	/
ttUploadReports	testGuideUrl: String - The URL to the test.guide instance to connect to credentialsId: String - Credentials for test.guide REST API. projectId: int - The test.guide project ID to upload to. useSettingsFromServer: boolean - Get and use upload settings from test.guide. additionalSettings:List<AdditionalSetting> - Additional ATX generator settings. reportIds: List<String> - reportIds to upload, ignore to upload all.	List<UploadResult>

Advanced Pipeline Examples

Conditional execution based on package check results

node {
    def checkResult = ttCheckPackage(
            testCasePath: 'test.pkg',
            executionConfig: [timeout: 1800, stopOnError: false]
    )

    if (checkResult.getResult() == 'SUCCESS') {
        ttRunPackage(testCasePath: checkResult.getTestCasePath())
    } else {
        //Handle Failed Check
        ttProvideLogs(timeout: 120)
    }
}

Using returned reportId to generate specific reports.

node {
    def testResult = ttRunPackage 'test.pkg'
    def reportId = testResult.getReportId()
    // Only generate reports for given reportIds, ignores the test.pkg run
    ttGenerateReports(
            generatorName: 'ATX',
            reportIds: [reportId]
    )

    // Only upload reports for given reportIds, ignores the test.pkg run
    /*
    def uploadResult = ttUploadReports(
            testGuideUrl: 'https://your-test-guide.url',
            credentialsId: 'serverCreds',
            projectId: 1,
            useSettingsFromServer: true,
            reportIds: reportIds
    )

    echo "Upload Result: ${uploadResult.collect { it.getUploadResult() }}"
     */
}

Objects and their properties

AnalysisConfig

Properties	Default Value	Description
analysisName: String	''	Name of the analysis to be executed.
mapping: String	''	Optional mapping which overwrites the default mapping. Will only be considered for analysis execution.
recordings: List<RecordingAsSetting>	[]	Recordings for analysis execution. Will only be considered for analysis execution.

ExecutionConfig

Properties	Default Value	Description
timeout: int	3600	Defines the maximum execution time in seconds running this test case. Set to 0 to disable timeout.
stopOnError: boolean	true	If test execution fails, stop running ecu.test/trace.check instances. Additionally, if ttCheckPackage is also selected the execution will be skipped on package check errors.
stopUndefinedTools: boolean	true	It only has an impact if Stop Tools on Error is also selected. Additionally, all tracetronic tools that are not defined by the Jenkins ETInstallations are stopped.
executePackageCheck: boolean	false	Perform the ttCheckPackage step before execution of package or project

PackageConfig

Properties	Default Value	Description
packageParameters: List<PackageParameter>	[]	Parameters for package execution.

TestConfig

Properties	Default Value	Description
tbcPath: String	''	The relative path of the .tbc file in the Configurations directory to be started for this execution. Use "KEEP" to use the currently loaded test bench configuration. If empty, no test bench configuration will be loaded.
tcfPath: String	''	The relative path of the .tcf file in the Configurations directory to be started for this execution. Use "KEEP" to use the currently loaded test configuration. If empty, no test configuration will be loaded.
forceConfigurationReload: boolean	false	If true, always reload the configuration even if the same one is still active. Hint: This flag is only required for ecu.test versions less than 2023.4!
constants: List<Constant>	[]	The configured global constants remain available throughout the entire test execution.

PublishConfig

Properties	Default Value	Description
timeout : int	3600	Defines the maximum execution time for publishing ecu.test artifacts in seconds. Set to 0 to disable timeout.
allowMissing : boolean	false	If true, empty test results do not lead to build failures. Otherwise, build status will be changed to failed.
keepAll : boolean	true	If true, archived artifacts will be kept on executor, otherwise artifacts will be deleted.

AdditionalSetting

Properties	Default Value
name: String	/
value: String	/

Constant

Properties	Default Value
label: String	/
value: String	/

PackageParameter

Properties	Default Value
label: String	/
value: String	/

RecordingAsSetting

Properties	Default Value	Description
path: String	""	The path must either be an absolute path or a path relative to the workspace directory.
recordingGroup: String	""	Name of the recording group the recording is to be assigned to. Only required for packages unless there is only one recording group (not used for analysis packages).
mappingNames: List<String>	[]	Names of the mapping items included in this recording. Only required for analysis packages unless there is only one recording (not used for packages).
deviceName: String	""	Optional device name. Required if the recording contains multiple devices and the mapping between device names in the test configuration and device names in the recording cannot be realized by format details. See "Supported file formats" in ecu.test help for more information.
formatDetails: String	""	Optional format details. Required if the recording cannot be interpreted with default format details. See "Supported file formats" in ecu.test help for more information.

CheckPackageResult

All given properties can be read via a getter method. (e.g. .getResult())

Properties	Description
result: String	Result of the package/project check execution Can either be 'ERROR' or 'SUCCESS'
testCasePath: String	Path to the file that should was checked. Can be package or project
issues: List<HashMap<String,String>	List of problems found in the package check execution

GenerationResult

All given properties can be read via a getter method. (e.g. .getGenerationResult())

Properties	Description
generationResult: String	Result of the report generation execution Can either be 'FINISHED' or 'ERROR'
generationMessage: String	ecu.test report generation message
reportOutputDir: String	location of ecu.test report

TestResult

All given properties can be read via a getter method. (e.g. .getReportId())

Properties	Description
reportId: String	reportId given by ecu.test
testResult: String	Result of the execution Can be 'NONE', 'SUCCESS', 'INCONCLUSIVE', 'FAILED' and 'ERROR'
reportDir: String	location of the report

UploadResult

All given properties can be read via a getter method. (e.g. .getUploadResult())

Properties	Description
uploadResult: String	Result of the report upload to test guide Can either be 'FINISHED' or 'ERROR'
uploadMessage: String	Response message from test.guide
reportLink: String	test guide link to the report. Will be empty if the upload was unsuccessful

ScanMode

enum ScanMode

Possible Values	Description
"PACKAGES_ONLY"	Only package files (.pkg) within this folder will be found/executed
"PROJECTS_ONLY"	Only project files (.prj) within this folder will be found/executed
"PACKAGES_AND_PROJECTS"	Both package and project files will be found/executed