Skip to content

espresso env variable settings #1319

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Feb 17, 2025
Merged

espresso env variable settings #1319

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
181 changes: 60 additions & 121 deletions docs/espresso-env-variables-settings.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
id: espresso-env-variables-settings
title: Espresso Environment Variable Settings
title: Setting Up Espresso Environment Variables
sidebar_label: Environment Variable Settings
description: Now you can run your Espresso framework on LambdaTest and this particular feature allows users to pass and retrieve environment variables (like STAGE, PROD, or DEV) during automated Android tests.
keywords:
Expand Down Expand Up @@ -48,35 +48,35 @@ import TabItem from '@theme/TabItem';
}}
></script>

Espresso is a powerful UI testing framework for Android that allows you to write automated UI tests for Android apps. When testing your Android apps on LambdaTest, you may need to pass environment variables for various configurations (e.g., STAGE, PROD, DEV) to manage different environments seamlessly.
This feature allows you to dynamically set and test environment variables during Espresso test execution on LambdaTest.

This guide will walk you through setting up, accessing, and using environment variables for Espresso tests on LambdaTest. You'll learn how to define and retrieve these variables using different configuration formats (JSON, YAML), integrate them with LambdaTest, and run your tests smoothly.
## Step 1: Create Variables in Your Test Suite
Define environment variables in your Espresso test suite to fetch the variable values during execution.

## Prerequisites

- Your LambdaTest [Username and Access key](https://accounts.lambdatest.com/security).
- Access to an **Android** app (.apk) and an **Espresso Test** app (.apk file).

:::tip

If you do not have any **Android** app (.apk) and an **Espresso Test** app (.apk) file, you can run your sample tests on LambdaTest by using our sample :link: [Android app](https://prod-mobile-artefacts.lambdatest.com/assets/docs/proverbial_android.apk) and a sample :link: [Espresso Test](https://prod-mobile-artefacts.lambdatest.com/assets/docs/proverbial_android_expressotest.apk).
```bash title="Sample Script"
String envVar = InstrumentationRegistry.getArguments().getString(ENV_VAR);
```

:::
``` bash title="Examples"
String stage = InstrumentationRegistry.getArguments().getString(“STAGE”);
String prod = InstrumentationRegistry.getArguments().getString(“PROD”);
```

## Step 1: Setup Environment Variable
## Step 2: Upload Your Application

Now, you need to export your environment variables *LT_USERNAME* and *LT_ACCESS_KEY* that are available in the [LambdaTest Profile page](https://accounts.lambdatest.com/detail/profile).
To begin testing, upload your Android application (.apk file) to LambdaTest's servers. You'll use our **REST API** for this process.

Run the below mentioned commands in your terminal to setup the CLI and the environment variables.
- **Authentication :** You'll need your LambdaTest Username and AccessKey. Combine them in the format `Username:AccessKey`.
- **Uploading the App :** Use **cURL command** to send a request to our API. The request should include the path to your application file (**appFile**).

<Tabs className="docs__val">

<TabItem value="bash" label="Linux / MacOS" default>

<div className="lambdatest__codeblock">
<CodeBlock className="language-bash">
{`export LT_USERNAME="${ YOUR_LAMBDATEST_USERNAME()}"
export LT_ACCESS_KEY="${ YOUR_LAMBDATEST_ACCESS_KEY()}"`}
{`curl -u "${ YOUR_LAMBDATEST_USERNAME()}:${ YOUR_LAMBDATEST_ACCESS_KEY()}" --location --request POST 'https://manual-api.lambdatest.com/app/uploadFramework' --form 'appFile=@"<PATH_OF_YOUR_ANDROID_APP>"' --form 'type="espresso-android"'`}
</CodeBlock>
</div>

Expand All @@ -86,32 +86,31 @@ export LT_ACCESS_KEY="${ YOUR_LAMBDATEST_ACCESS_KEY()}"`}

<div className="lambdatest__codeblock">
<CodeBlock className="language-powershell">
{`set LT_USERNAME="${ YOUR_LAMBDATEST_USERNAME()}"
set LT_ACCESS_KEY="${ YOUR_LAMBDATEST_ACCESS_KEY()}"`}
{`curl -u "${ YOUR_LAMBDATEST_USERNAME()}:${ YOUR_LAMBDATEST_ACCESS_KEY()}" --location --request POST "https://manual-api.lambdatest.com/app/uploadFramework" --form "appFile=@"<PATH_OF_YOUR_ANDROID_APP>"" --form "type=\"espresso-android\""`}
</CodeBlock>
</div>

</TabItem>
</Tabs>

## Step 2: Upload your Application and Test Suite
:::info
- Provide the path of your android application in the above URL in place of `<PATH_OF_YOUR_ANDROID_APP>`
- Response of above cURL will be a **JSON** object containing the `App URL` of the format - `lt://APP123456789123456789` and will be used in the last step.
:::

### Upload your App
## Step 3: Upload Your Test Suite

Upload your **android** application (.apk file) to the LambdaTest servers using our **REST API**. You need to provide your **Username** and **AccessKey** in the format ```Username:AccessKey``` in the **cURL** command for authentication. Make sure to add the path of the **appFile** in the cURL request.
Upload your Espresso test suite (.apk) file to LambdaTest servers using our REST API.

Here is an example cURL request to upload your app using our REST API:
The following sample cURL command shows how to upload a test suite:

<Tabs className="docs__val">

<TabItem value="bash" label="Linux / MacOS" default>

<div className="lambdatest__codeblock">
<CodeBlock className="language-bash">
{`curl -u "${ YOUR_LAMBDATEST_USERNAME()}:${ YOUR_LAMBDATEST_ACCESS_KEY()}" \\
--location --request POST 'https://manual-api.lambdatest.com/app/uploadFramework' \\
--form 'appFile=@"/Users/macuser/Downloads/proverbial.ipa"' \\
--form 'type="espresso-android"'`}
{`curl -u "${ YOUR_LAMBDATEST_USERNAME()}:${ YOUR_LAMBDATEST_ACCESS_KEY()}" --location --request POST 'https://manual-api.lambdatest.com/app/uploadFramework' --form 'appFile=@"<PATH_OF_YOUR_TEST_SUITE_APP>"' --form 'type="espresso-android"'`}
</CodeBlock>
</div>

Expand All @@ -121,55 +120,58 @@ Here is an example cURL request to upload your app using our REST API:

<div className="lambdatest__codeblock">
<CodeBlock className="language-powershell">
{`curl -u "${ YOUR_LAMBDATEST_USERNAME()}:${ YOUR_LAMBDATEST_ACCESS_KEY()}" -X POST "https://manual-api.lambdatest.com/app/uploadFramework" -F "appFile=@"/Users/macuser/Downloads/proverbial.ipa"" -F "type="espresso-android""`}
{`curl -u "${ YOUR_LAMBDATEST_USERNAME()}:${ YOUR_LAMBDATEST_ACCESS_KEY()}" --location --request POST "https://manual-api.lambdatest.com/app/uploadFramework" --form "appFile=@"<PATH_OF_YOUR_TEST_SUITE_APP>"" --form "type=\"espresso-android\""`}
</CodeBlock>
</div>

</TabItem>
</Tabs>

:::note
Response of above cURL will be a **JSON** object containing the `App URL` of the format - `APP123456789123456789` and will be used in the last step as `appId`.
:::info
- Provide the path of your android application in the above URL in place of `<PATH_OF_YOUR_TEST_SUITE_APP>`
- Response of above cURL will be a **JSON** object containing the `App URL` of the format - `lt://APP123456789123456789` and will be used in the last step.
:::

### Upload your Test Suite

Upload your **test suite** (.apk file) to the LambdaTest servers using our **REST API**. You need to provide your **Username** and **AccessKey** in the format `Username:AccessKey` in the **cURL** command for authentication. Make sure to add the path of the **appFile** in the cURL request. Here is an example cURL request to upload your app using our REST API:

<Tabs className="docs__val">

<TabItem value="bash" label="Linux / MacOS" default>

<div className="lambdatest__codeblock">
<CodeBlock className="language-bash">
{`curl -u "${ YOUR_LAMBDATEST_USERNAME()}:${ YOUR_LAMBDATEST_ACCESS_KEY()}" \\
--location --request POST 'https://manual-api.lambdatest.com/app/uploadFramework' \
--form 'appFile=@"/Users/macuser/Downloads/proverbial_ios_xcuitest.ipa"' \
--form 'type="espresso-android"'`}
</CodeBlock>
</div>
## Step 4: Executing The Test

</TabItem>
- You will need **base64 encoded authentication** in order to execute your Espresso automation test suite. Enter your `username:accesskey` in **[Basic Authentication Header Generator](https://mixedanalytics.com/knowledge-base/api-connector-encode-credentials-to-base-64/)** to generate your auth token.

<TabItem value="powershell" label="Windows" default>
Take note of the base64 encoded authentication which needs to be added in the next step.

<div className="lambdatest__codeblock">
<div className="lambdatest__codeblock">
<CodeBlock className="language-powershell">
{`curl -u "${ YOUR_LAMBDATEST_USERNAME()}:${ YOUR_LAMBDATEST_ACCESS_KEY()}" --location --request POST "https://manual-api.lambdatest.com/app/uploadFramework" --form "appFile=@"C:/Users/varunkumarb/Downloads/proverbial_ios_xcuitest.ipa"" --form "type=\"espresso-android\""`}
{`${ YOUR_LAMBDATEST_USERNAME()}:${ YOUR_LAMBDATEST_ACCESS_KEY()}`}
</CodeBlock>
</div>

</TabItem>
</Tabs>

:::note
- Once you have uploaded your app and test suite, you can execute your test by running the following command:

> Enter your **BASIC_AUTH_TOKEN**, **APP_ID** (generated in the first step) and **TEST_SUITE_ID** (generated in the second step) in the below command.

Response of above cURL will be a **JSON** object containing the `App URL` of the format - `APP123456789123456789` and will be used in the next step as ``testSuiteAppId``

:::
```bash
curl --location --request POST 'https://mobile-api.lambdatest.com/framework/v1/espresso/build' \
--header 'Authorization: Basic BASIC_AUTH_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
"app" : "APP_ID",
"testSuite": "TEST_SUITE_ID",
"device" : ["Galaxy S21 5G-12"],
"queueTimeout": 10800,
"IdleTimeout": 150,
"deviceLog": true,
"network": false,
"build" : "Proverbial-Espresso"
# highlight-start
"envVariables":{ //setting up environment variables
"STAGE":"stg1",
"PROD":"prod1"
}
# highlight-end
}'
```

## Step 3: Configure YAML in your Test Suite
Enter your `<RELATIVE_APP_PATH>` and `<RELATIVE_TEST_SUITE_PATH>` in the YAML file
## Run your test in HyperExecute
To execute your test suite in HyperExecute, configure your YAML file by specifying the `<RELATIVE_APP_PATH>` and `<RELATIVE_TEST_SUITE_PATH>`.

```yaml
---
Expand Down Expand Up @@ -203,70 +205,7 @@ framework:
values: ["<className>/<className/testName>", "<className>/<className/testName>"]
```

## Step 4: Generate Reports and Artifacts
To generate artifacts for your XCUI tests, add the `artifacts: true` and `report: true` flag in your YAML file:

```yaml
report: true

framework:
name: "android/espresso"
args:
artifacts: true
...//
```

To download these artifacts in your local machine, you can pass the `--download-artifacts` and `--download-report` flag with the CLI command to execute the tests as shown in the next step.

## Step 5: Execute your Test Suite

> **NOTE :** In case of macOS, if you get a permission denied warning while executing CLI, simply run **`chmod u+x ./hyperexecute`** to allow permission. In case you get a security popup, allow it from your **System Preferences** → **Security & Privacy** → **General tab**.

Run the below command in your terminal at the root folder of the project:

```bash
./hyperexecute --config RELATIVE_PATH_OF_YOUR_YAML_FILE --download-artifacts --download-report
```

OR use this command if you have not exported your username and access key in the step 2.

<div className="lambdatest__codeblock">
<CodeBlock className="language-bash">
{`./hyperexecute --user ${ YOUR_LAMBDATEST_USERNAME()} --key ${ YOUR_LAMBDATEST_ACCESS_KEY()} --config RELATIVE_PATH_OF_YOUR_YAML_FILE --download-artifacts --download-report`}
</CodeBlock>
</div>

## Step 6: Monitor the Test Execution

Visit the dashboard and check your job status.

<img loading="lazy" src={require('../assets/images/espresso/environment-variable-success.png').default} alt="automation-dashboard" width="1920" height="868" className="doc_img"/>

## Benefits of Using Environment Variables in Espresso

### Environment Flexibility:
Easily switch between different configurations (STAGE, PROD, DEV) without changing the test code.

### Reusability:
Use the same test script for different environments by only changing the environment variables.

### Cleaner Configurations:
Manage and switch environment settings via Postman or YAML without modifying your test code.

### Cross-Platform Compatibility:
LambdaTest allows you to run your Espresso tests on multiple Android devices in parallel, ensuring broader coverage.

## Troubleshooting Tips
### Problem: Environment Variables Not Loading
Ensure that the environment variables are correctly defined in Postman or YAML and properly linked to LambdaTest.
Double-check that the correct environment variable names are being used in your Espresso test code.

### Problem: Environment Variable Not Found
Verify that the environment variable name in the LambdaTest capability and the test code match exactly.
Check the syntax in the Postman or YAML file for any typos or missing parameters.

### Problem: Test Fails on LambdaTest
Make sure the Appium server or Espresso test is correctly set up on LambdaTest.
Ensure that the environment variable values are being passed and accessed properly in the code.


25 changes: 10 additions & 15 deletions sidebars.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2595,22 +2595,17 @@ module.exports = {
id: "getting-started-with-espresso-testing",
},
{
type: "doc",
type: "category",
collapsed: true,
label: "Supported Capabilities",
id: "espresso-supported-capabilities",
},
// {
// type: "category",
// collapsed: true,
// label: "Supported Capabilities",
// link: {
// type: "doc",
// id: "espresso-supported-capabilities",
// },
// items: [
// "espresso-env-variables-settings",
// ],
// },
link: {
type: "doc",
id: "espresso-supported-capabilities",
},
items: [
"espresso-env-variables-settings",
],
},
{
type: "doc",
label: "RegEx in Espresso",
Expand Down
Loading