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:

1. An active TestProject account which can be created for free at https://testproject.io.
2. 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 to apk/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