Running Tests With a Pipeline Script

appPath

String

The absolute or workspace relative path to the app executable (.apk or .ipa) that should be uploaded and targeted in this test run. For example, /path/to/app.ipa. Default value: the latest app uploaded for this project.

biometricInstrumentation

Boolean

Specifies whether to enable instrumentation on the app in order to bypass biometric authentication during testing. Value is set to false when parameters do not pass.

cloudUrl

String

The BitBar Cloud URL this run should target. For example, https://cloud.bitbar.com. The default value: the cloud URL that was specified in the Jenkins /config page BitBar Cloud section. Ensure that you also specify credentialsId if you specify this option.

credentialsId

String

The login credentials ID for the BitBar Cloud, which is your API Key.

dataPath

String

The absolute or workspace-relative path to a .zip file that your test uses as additional data during a run. For example, /path/to/extra~data.zip. Do not use an additional data package.

deviceGroupId

String

Required. Used to specify which device(s) the test run will target. It's a number that you can find by visiting /#testing/devices in the BitBar Cloud and looking to the right where it says Device Groups. Under each "box" of devices, there is a number ID 12345 or such. That number, 12345, in this case, is the deviceGroupId. For example, 12345.

downloadScreenshots

Boolean

Specifies whether or not to download the screenshots (if any) after the test run completes. The default value: false; commands not to download screenshots (only logs) after the test run.

This parameter should be placed within the waitForResultsBlock array.

failBuildIfThisStepFailed

Boolean

Specifies whether the runInCloud build step should cause the whole Jenkins build to fail if there is an error. You can use this option to allow your Jenkins build to pass, even if an error occurred in the BitBar runInCloud step. The default value: false; a build doesn't fail even if there is an error.

This parameter is unrelated to the success or failure of tests conducted in the cloud; its sole purpose is to determine whether the step executes without issues or encounters exceptions.

forceFinishAfterBreak

Boolean

Whether or not to abort the BitBar Cloud run after waiting for the results for a set amount of time after the run started. If set to false, the cloud run is allowed to finish on its own even after the Jenkins job stopped waiting for it. The default value: false; commands not to abort the cloud run after waiting for it to finish.

This parameter should be placed within the waitForResultsBlock array.

frameworkId

Integer

A parameter used to specify the framework in which you want to execute your test. This parameter allows you to indicate the specific testing framework or environment that your tests should utilize.

You can obtain a list of all available frameworkIds associated with the user by making an API call to the following endpoint:

https://cloud.bitbar.com/cloud/api/v2/
users/{userId}/available-frameworks

Replace {userId} with the user's unique identifier. By referencing the available frameworkId retrieved from this API call, you can select the appropriate framework for your test execution, ensuring compatibility and optimal testing environment configuration.

hookURL

String

The URL to which the BitBar Cloud will send a POST request when the test run finishes. Ensure that the address is accessible by the global internet or included in the BitBar Cloud allow list. This can be used by enterprise systems that need to react to completed test runs. For example, https://example.com/bitbar~cloud~endpoint.

This parameter should be placed within the waitForResultsBlock array.

The default value:

JENKINS_URL/plugin/
testdroid~run~in~cloud/api/
json/cloud~webhook

This default value can be used if testRunStateCheckMethod: "HOOK_URL" is set. The hook URL info is then used by the BitBar Run~in~Cloud plugin to determine that a test run has finished.

The data sent in the POST request is a short UTF-8 snippet in the following format:

test=12345&proj=45678&s=SUCCESS&dev=123,456,789

keyValuePairs

String

Additional environment variables provided to the test run. This can be used for advanced logic in test cases where the test might behave differently depending on some value. Key-value pairs should be semicolon-separated (;), and the key and value should be colon-separated (:).

For example, SOME_PARAM:some~value;ANOTHER_PARAM:another~value.

The default value: empty string.

language

String

The locale (language) that should be set on the phone when the run starts. Has to be a locale supported by Android.

For example, zh-TW; Chinese, Taiwan.

The default value: en-US; English, United States.

Androids only.

projectId

String

Required. Defines which BitBar Cloud project this test run should be included in. By extension, this also selects the target platform, Android/iOS. This value is a number that you can find by going to Projects in the BitBar Cloud and reading the URL when you select a project. For instance, if the URL in the browser is https://cloud.bitbar.com/#testing/projects/12345, then the project ID is 12345.

For example, 12345.

resultsPath

String

The absolute or workspace-relative path to a folder where results should be downloaded after the run completes.

For example, ./my~results.

The default value: Jenkins workspace.

This parameter should be placed within the waitForResultsBlock array.

scheduler

String

Defines in what order tests should be run in the BitBar Cloud, in case multiple devices are targeted.

screenshotsDirectory

String

The location on the device from where test screenshots should be pulled after a test run.

For example, /sdcard/screenshots.

The default value: /sdcard/test~screenshots.

Androids only.

testCasesSelect

String

The value specifies a way (package/class) to narrow down the test cases that should be run. This parameter applies only to projects of the Android Instrumentation type - Espresso tests.

Androids only.

Requires testCasesValue to be set to something meaningful.

testCasesValue

String

If testCasesSelect is specified, this parameter defines the package/class by which to filter test cases. This parameter applies only to projects of the Android Instrumentation type - Espresso tests.

For example, com.mycompany.espressotests.AuthenticationTest.

An example of a class that might be defined in your tests.

testPath

String

The absolute or workspace-relative path to a test package that should be uploaded and run in the BitBar Cloud. Most often, a .zip or .apk file. For AppCrawler projects, this parameter should be omitted.

For example, /path/to/my/tests.zip.

The default value: use the latest test package that was uploaded to this project.

testRunName

String

Custom name for the test run in the BitBar Cloud.

For example, My test run.

By default, the cloud will assign a name like Test Run 45, depending on the number of previous runs in the cloud project.

testRunner

String

The test runner class that will execute Espresso tests. Refer to InstrumentationTestRunner for details.

For example, android.support.test.runner.AndroidJUnitRunner.

The default value: android.test.InstrumentationTestRunner.

Androids only.

testRunStateCheckMethod

String

Specifies the method by which the plugin will check if the BitBar Cloud run has finished.

This parameter should be placed within the waitForResultsBlock array.

testTimeout

String

A value in seconds, how long the cloud test can run before it is forced to shut down.

For example, 3600 (one hour).

The default value: 600 (10 minutes).

waitForResultsBlock

Array

In a pipeline script, this parameter functions similarly to waitForResults:true but operates within a block context. This block signals the system to wait for results before proceeding, offering more precise control over waiting behavior by encapsulating multiple parameters.

waitForResultsTimeout

String

A value in seconds specifies how long the build step should wait for cloud results.

For example, 3600.

This parameter should be placed within the waitForResultsBlock array.

withAnnotation

String

Runs only test cases that have a certain Java annotation specified. This parameter applies only to projects of the Android Instrumentation type - Espresso tests.

For example, com.android.foo.MyAnnotation. Doesn't filter by annotations but instead runs all test cases.

Androids only.

withoutAnnotation

String

Does not run test cases that have a certain Java annotation specified. This parameter applies only to projects of the Android Instrumentation type - Espresso tests.

For example, com.android.foo.MyAnnotation. Doesn't filter by annotations but instead runs all test cases.

Androids only.