TestProject plugin for Jenkins
TestProject plugin for Jenkins provides an easy way to execute TestProject jobs, update applications, data sources, project parameter, test packages and generate configuration for the TestProject Agent.
Prerequisites
In order to use this plugin you need to have:
- An active TestProject account which can be created for free at https://testproject.io.
- At least one registered and running TestProject Agent.
How to use
- Install the plugin.
- Go to project Configure > TestProject.
- Set your TestProject API Key (which can be obtained here).
This plugin supports both FreeStyle and Pipeline jobs.
Build Steps
Running a TestProject Job
Using this step, you can trigger TestProject jobs as part of your Jenkins build. To trigger a job, you need to provide the following parameters:
projectId
- The ID of the project containing the job.jobId
- The ID of the job to execute.agentId
(optional) - The ID of the TestProject agent that will execute the job. Leave this field empty to use the default agent defined for this job.waitJobFinishSeconds
- How many seconds should the step wait for the automation job to finish. If 0 is provided, the setup will not wait for the job to finish execution.junitResultsFile
(optional) - Path (including the file name) to a file where the JUnit XML report will be stored. The file path can be absolute or relative to your workspace.executionParameters
(optional) - A JSON object that allows you to override the job's default settings and parameters for a single execution. Here's an example:
{
"browsers": [
"Chrome"
],
"devices": [
"AAA111BBB"
],
"queue": true,
"restartDriver": true,
"projectParameters": {
"ProjectParameter1": "Value1",
"ProjectParameter2": "Value2",
"ProjectParameter3": "Value3"
},
"testParameters": [
{
"testId": "string",
"testPosition": 0,
"dataSourceId": "string",
"reinstallApp": true,
"data": [
{
"TestParameter1": "Value1",
"TestParameter2": "Value2",
"TestParameter3": "Value3"
}
]
}
],
"tags": [
"ForCI",
"Server",
"Lab1"
]
}
Please visit our API documentation to read more about using execution parameters when running a job.
Free Style syntax
Pipeline syntax
tpJobRun projectId: '<PROJECT_ID>', jobId: '<JOB_ID>', agentId: '<AGENT_ID>', waitJobFinishSeconds: 180, junitResultsFile: '<JUNIT_RESULTS_FILE>', executionParameters: '<EXECUTION_PARAMETERS>'
Running a TestProject Test
Using this step, you can trigger TestProject tests as part of your Jenkins build. To trigger a test, you need to provide the following parameters:
projectId
- The ID of the project containing the test.testId
- The ID of the test to execute.agentId
- The ID of the TestProject agent that will execute the test.browser
- The name of the browser to execute the test on.device
- The UDID of the mobile device to execute the test on.waitTestFinishSeconds
- How many seconds should the step wait for the automation test to finish. If 0 is provided, the setup will not wait for the test to finish execution.junitResultsFile
(optional) - Path (including the file name) to a file where the JUnit XML report will be stored. The file path can be absolute or relative to your workspace.executionParameters
(optional) - A JSON object that allows you to override the test's default settings and parameters for a single execution. Here's an example:
{
"testParameters": {
"ApplicationURL": "https://example.testproject.io",
"Email": "example@testproject.io"
},
"projectParameters": {
"Name": "John Doe",
"Age": 30
},
"tags": [
"ForCI",
"Server",
"Lab1"
]
}
Please visit our API documentation to read more about using execution parameters when running a test.
Free Style syntax
Pipeline syntax
tpTestRun projectId: '<PROJECT_ID>', testId: '<TEST_ID>', agentId: '<AGENT_ID>', browser: '<BROWSER_NAME>', waitTestFinishSeconds: 180, junitResultsFile: '<JUNIT_RESULTS_FILE>', executionParameters: '<EXECUTION_PARAMETERS>'
Updating a Mobile Application (apk/ipa) File
Using this step, you can update an existing Android or iOS application file as part of your build.
The step accepts the following parameters:
projectId
- The ID of the project in containing the application.applicationId
- The ID of the application to update.filePath
- The path toapk/ipa
file. The file path can be absolute or relative to your workspace.
Free Style syntax
Pipeline syntax
tpAppUpdateFile appId: '<APP_ID>', filePath: '<FILE_PATH>', projectId: '<PROJECT_ID>'
Updating a Web Application URL
Using this step, you can update the URL of a web application.
The step accepts the following parameters:
projectId
- The ID of the project containing the application.applicationId
- The ID of the application to update.applicationUrl
- The new URL address.
Free Style syntax
Pipeline syntax
tpAppUpdateURL appId: '<APP_ID>', applicationUrl: '<APP_URL>', projectId: '<PROJECT_ID>'
Updating a Data Source
Using this step, you can update an existing data source file (.csv
).
This step accepts the following parameters:
projectId
- The ID of the project containing the data source.dataSourceId
- The ID of the data source to update.filePath
- The path to the data source (.csv
) file. The file path can be absolute or relative to your workspace.
Free Style syntax
Pipeline syntax
tpDataSourceUpdate dataSourceId: '<DATA_SOURCE_ID>', filePath: '<FILE_PATH>', projectId: '<PROJECT_ID>'
Updating a Project Parameter
Using this step, you can update the value of any project parameter in your project.
The step accepts the following parameters:
projectId
- The ID of the project containing the parameter.parameterId
- The ID of the parameter to update.value
- The new value that should be assigned to the parameter.
Free Style syntax
Pipeline syntax
tpParamProjectUpdate parameterId: '<PARAMETER_ID>', parameterValue: '<PARAMETER_VALUE>', projectId: '<PROJECT_ID>'
Updating a Test Package
Using this step, you can update an existing test package (coded test) in your project.
The step accepts the following parameters:
projectId
- The ID of the project containing the test package.testPackageId
- The ID of the test package to update.filePath
- The path to the new test package file (.jar
/.dll
/.zip
). The file path can be absolute or relative to your workspace.resolveConflicts
[true/false] - Should TestProject try to automatically resolve conflicts.
A conflict may arise if the updated test package is used by other tests or the new packages contains breaking changes such as removed test cases, etc.
Free Style syntax
Pipeline syntax
tpTestPackageUpdate filePath: '<FILE_PATH>', projectId: '<PROJECT_ID>', resolveConflicts: '<TRUE/FALSE>', testPackageId: '<TEST_PACKAGE_ID>'
Generating TestProject Agent Configuration
Using this step, you can generate configuration for a TestProject Agent.
This can be used to allow a TestProject Agent running in a docker container to automatically register, execute a job and terminate on completion.
This step accepts the following parameters:
-
agentAlias
- An alias (name) for the agent.This parameter is optional. If no value is provided, TestProject will generate an alias for you.
-
projectId
- The ID of the project containing the job to execute. -
jobId
- The ID of the job to execute. -
jobParameters
- A JSON object containing job execution parameters.This parameter is optional. If no value is provided, the job will be executed with its default configuration.
Example:
{ "browsers": [ "ChromeHeadless", "FirefoxHeadless" ] }
Please visit our docker hub page to read more about TestProject Agents containers
Pipeline syntax
tpAgentConfig alias: '<AGENT_ALIAS>', jobId: '<JOB_ID>', jobParameters: '<JOB_PARAMETERS>', projectId: '<PROJECT_ID>'
To read the agent configuration object in your pipeline script and access to the config
property, follow the example below:
node {
def agentConfig = tpAgentConfig(
alias: '<AGENT_ALIAS>',
jobId: '<JOB_ID>',
jobParameters: '<JOB_PARAMETERS>',
projectId: '<PROJECT_ID>')
print(agentConfig.config)
}
Additional info
WebSite: https://testproject.io
Blog: https://blog.testproject.io
Forum: https://forum.testproject.io
Addons: https://addons.testproject.io
Docker Hub: https://hub.docker.com/r/testproject/agent
YouTube: https://www.youtube.com/channel/UCEAPPxNvHT74Xj6Ixt28mNw