Lambda Hooks For Appium Automation
This document will help you provide lambdahooks which can be used to improve your test scripts to easily debug your test cases for App Automation on Real Devices on TestMu AI Cloud.
Adding custom status & remark
To add custom status & remark, just add the code snippet using the JavascriptExecutor.
JavascriptExecutor accepts two arguments as shown below:
| Arguments | Example |
|---|---|
status | failed OR passed |
remark | Any remark can be added here limited to 255 characters. |
((JavascriptExecutor) driver).executeScript("lambda-hook: {\"action\": \"setTestStatus\",\"arguments\": {\"status\":\"failed\", \"remark\":\"This is a sample remark for failed test \"}} ");
Here is a sample automation script in Java for the sample status & remark. Ensure to update the app_url, username & accesskey in the below code.
import io.appium.java_client.AppiumDriver;
import io.appium.java_client.MobileBy;
import io.appium.java_client.MobileElement;
import org.openqa.selenium.JavascriptExecutor;
import org.openqa.selenium.remote.DesiredCapabilities;
import java.net.MalformedURLException;
import java.net.URL;
public class vanilla_android {
private static AppiumDriver driver;
public static void main(String args[]) throws MalformedURLException, InterruptedException {
try {
DesiredCapabilities capabilities = new DesiredCapabilities();
capabilities.setCapability("deviceName", "Galaxy S20");
capabilities.setCapability("platformVersion", "11");
capabilities.setCapability("platformName", "Android");
capabilities.setCapability("isRealMobile", true);
capabilities.setCapability("app", "APP_ID"); //Enter your app url
capabilities.setCapability("build", "Java Vanilla - Android");
capabilities.setCapability("name", "Sample Test Java");
//Enter your Username & Accesskey here:
driver = new AppiumDriver(new URL("https://" +userName + ":" + accessKey + "@mobile-hub.lambdatest.com/wd/hub"), capabilities);
MobileElement color = (MobileElement) driver.findElement(MobileBy.id("com.lambdatest.proverbial:id/color"));
color.click();
//Javascript Executor for marking the status and custom remark.
((JavascriptExecutor) driver).executeScript("lambda-hook: {\"action\": \"setTestStatus\",\"arguments\": {\"status\":\"failed\", \"remark\":\"This is a sample remark for failed test \"}} ");
}
// The driver.quit statement is required, otherwise the test continues to execute, leading to a timeout.
driver.quit();
}
}
Once you have added the code snippet, the status and remark will be visible on the TestMu AI App Automation Dashboard as shown below:
Update Test Name
To update the name of the test, just add the code snippet using the JavascriptExecutor.
| Arguments | Example |
|---|---|
lambda-name | For changing the Test Name. |
((JavascriptExecutor) driver).executeScript("lambda-name=TestName");
Differentiating Test Cases in Single Session
TestMu AI has introduced a LambdaHook to help automation engineers differentiate between multiple test cases within a single Appium session. This feature aims to improve debugging capabilities, making it easier to identify which test cases may be causing errors or taking longer to execute.
The test case hooks (lambda-testCase-start, lambda-testCase-end and lambda-testCase-status) are supported for App Automation on both Real Devices and Virtual Devices. They are not supported for web automation sessions.
Adding Lambda Hooks
You can use LambdaHooks to start and end a test case within a single Appium session.
Test Case Start
To start a test case, use the lambda-testCase-start hook:
// To start a test case
((JavascriptExecutor) driver).executeScript("lambda-testCase-start=find Name");
Test Case End
To end a test case, use the lambda-testCase-end hook:
// To end a test case
((JavascriptExecutor) driver).executeScript("lambda-testCase-end=find Name");
Marking the Status of a Test Case
By default, TestMu AI derives the status of each test case from its commands: if any command executed between lambda-testCase-start and lambda-testCase-end fails, the test case is marked Failed. This is not always the real result. A command may fail and then pass on a retry, or a command may be expected to fail as part of a negative check (for example, verifying that an element is not displayed).
Use the lambda-testCase-status hook to send the real result from your framework. The status you send overrides the derived status of the test case in Test Case Insights.
Test Case Status
Call lambda-testCase-status after lambda-testCase-start and before lambda-testCase-end:
// To mark the open test case as passed or failed
((JavascriptExecutor) driver).executeScript("lambda-testCase-status=passed");
To store a remark with the status, pass the status as JSON. The remark is optional and is limited to 255 bytes; longer remarks are truncated.
((JavascriptExecutor) driver).executeScript("lambda-testCase-status={\"status\":\"passed\",\"remark\":\"404 on first attempt, retry succeeded\"}");
| Argument | Description |
|---|---|
status | passed or failed. The value is case-insensitive. Any other value, such as skipped, is ignored. |
remark | Optional. Any text explaining the status, limited to 255 bytes. Supported only in the JSON form. |
Example
The following examples mark each test case with the result your framework reports, so a retry that passed or an expected failure does not mark the test case as failed.
- Java
- Python
- Cucumber (Java)
for (TestCase tc : suite) {
driver.executeScript("lambda-testCase-start=" + tc.getName());
boolean passed = tc.run(); // your framework handles retries and negative checks
driver.executeScript("lambda-testCase-status=" + (passed ? "passed" : "failed"));
driver.executeScript("lambda-testCase-end=" + tc.getName());
}
driver.execute_script(f"lambda-testCase-start={name}")
# ... test steps ...
driver.execute_script("lambda-testCase-status=passed")
driver.execute_script(f"lambda-testCase-end={name}")
@After
public void markTestCase(Scenario scenario) {
String status = scenario.isFailed() ? "failed" : "passed";
((JavascriptExecutor) driver).executeScript("lambda-testCase-status=" + status);
((JavascriptExecutor) driver).executeScript("lambda-testCase-end=" + scenario.getName());
}
How the Final Status is Decided
| Scenario | Final status of the test case |
|---|---|
No lambda-testCase-status call | Derived from commands: Failed if any command failed, otherwise Passed. This is the same behavior as before. |
lambda-testCase-status called once | The status you sent, even if it differs from the derived status. For example, failed marks the test case as Failed even when every command passed. |
lambda-testCase-status called more than once | The last valid status you sent. |
Invalid or empty value (for example, skipped) | The call is ignored and the test case keeps its previous status. If no valid status was sent, the derived status is used. |
Called before any lambda-testCase-start, or after lambda-testCase-end and before the next start | The call is ignored, because no test case is open. No test case is changed. |
| Test case started but never ended | The test case is still recorded with the status you sent. |
JSON without a status, or malformed JSON | The call is ignored. If no valid status was sent, the derived status is used. |
Each call returns a message to your script stating whether the status was set or why it was ignored (for example, no active test case or an invalid status). Ignored calls never fail the session and appear in the command logs as warnings, not errors.
lambda-testCase-status only sets the status of a test case. It does not change the session status, which you continue to set with lambda-status or setTestStatus. A session marked Passed can still contain test cases marked Failed, and the other way around.
Labeling and Filtering Command Logs
Any command logs executed between lambda-testCase-start and lambda-testCase-end will be labeled with the name you provide. The name should not exceed 255 characters.
You can also filter the command logs based on these labels.A screenshot has been provided below, demonstrating the use of labels and how to filter command logs based on them.

Viewing Test Cases and Their Trends
Every test case you mark with the start and end hooks is also listed on the automation session details page. Click the test case selector above the command logs to open the Select Test Case panel, which lists all the test cases recorded in the session along with the trend of their last five runs.

The panel shows the following details:
| Detail | Description |
|---|---|
| All Test Cases | The list of every test case captured between the lambda-testCase-start and lambda-testCase-end hooks, along with the total count of test cases in the session. |
| Search test case | Search for a test case using the name you passed to the hook. This is helpful when a single session runs a large number of test cases. |
| Status | A green tick indicates that the test case passed in the current session and a red cross indicates that it failed. |
| Last 5 runs | The strip of squares next to each test case shows the result of its last five runs, with the latest run on the right. Green denotes a passed run and red denotes a failed run. |
Selecting a test case from the panel filters the command logs to the commands executed between that test case's start and end hooks, so you can jump straight to the section of the session you want to debug.
The Last 5 runs trend lets you tell a genuinely broken test case from a flaky one without opening older sessions. A test case that is red across all five runs points to a consistent failure, whereas a mix of red and green points to flakiness that is worth investigating separately.
Command Annotations
Command Annotations allow you to add metadata and debugging information to your test scripts. They work similarly to LambdaHooks by providing structured logs on the TestMu AI Automation Dashboard, making it easier to track test execution, debug failures, and navigate specific test sections.

Using Command Annotations
Annotation Start
Verifieddriver.execute_script("lambdatest_executor: {\"action\": \"stepcontext\", \"arguments\": {\"data\": \"youtube\", \"level\": \"debug\"}}");
Arguments:
| Argument | Description |
|---|---|
data | String value representing the information you want to log. |
level | Log severity level. Acceptable values: info (default), debug, warn, error. |
Annotation End
To close the executor at the end of your script, pass data as an empty string:
driver.execute_script("lambdatest_executor: {\"action\": \"stepcontext\", \"arguments\": {\"data\": \"\"}}");
Mutual exclusivity: Test case and Command Annotations cannot be used together in the same script. You can only use one of them per session.
Install and Uninstall App Hooks
TestMu AI now allows you to install and uninstall apps in the middle of your automated tests. This means you don’t need to restart the session every time you want to switch apps, upgrade them, or clean up the device. TestMu AI enables you to install and uninstall applications during automation test execution by using commands that can be run through WebDriver's script execution functionality.
Install App
You can install apps uploaded to the TestMu AI platform directly within your automation scripts using the lambda-install-app command followed by the app’s ID. This ID can be either the TestMu AI-generated ID or a custom ID assigned during upload.
Python example:
Verifieddriver.execute_script("lambda-install-app=myApp")
driver.execute_script("lambda-install-app=lt://APP100000000123456789123456789")
driver.execute_script("lambda-install-app=filename=MyApp.apk")
You can also pass filename=<file-name> to install the latest uploaded app with that File Name, as shown in App Manager. Installing by file name during a session is not available on iOS simulators. For details on how the app is selected, see Use the File Name Instead of the App ID.
JavaScript example:
Verifiedawait browser.execute("lambda-install-app", {
/* Change the App URL */
appUrl: "lt://APP1234567890ABCDEF1234567890",
/* Optional */
retainData: true
});
Uninstall App
You can uninstall apps during the execution of an automation test using the command lambda-uninstall-app followed by the app's package name (for Android apps) or bundle ID (for iOS apps).
Python example:
Verifieddriver.execute_script("lambda-uninstall-app=com.myApp.beta")
driver.execute_script("lambda-uninstall-app=com.apple.myApp")
JavaScript example:
Verified/* Change the App ID */
const APP_ID = "com.lambdatest.proverbial";
await browser.execute(`lambda-uninstall-app=${APP_ID}`);
Test App Upgrades with Hooks
Testing app upgrades is important because users often update to the latest version instead of reinstalling the app. To ensure existing user data is preserved and the app continues to function properly after an upgrade, you can use the following hooks:
Python example:
- Android
- iOS
# Payload required to retain app data while uninstalling it
data = {
"appPackage": "sampleapp.android.app",
"retainData": True
}
driver.execute_script("lambda-uninstall-app", data)
# Payload required to reuse data of the old app while installing the new one
data = {
"appUrl": "lt://APPID",
"retainData": True
}
driver.execute_script("lambda-install-app", data)
# Send the current app in background
driver.background_app(-1)
# Payload required while installing the new upgrade
data = {
"appUrl": "lt://APPID",
"retainData": True
}
driver.execute_script("lambda-install-app", data)
# Note : In case of enterprise app, user have to pass the below payload
data = {
"appUrl": "lt://APPID",
"resignApp": False,
"retainData": True
}
Validation Errors
You might encounter some errors while using these features. The following are some common validation errors and their meaning:
| Error Message | Meaning |
|---|---|
No app_url has been provided for lambda-install-app. Please check and try again. | The install command is missing the app URL or ID. |
The app provided for lambda-install-app is not accessible. Please check and try again. | The app ID does not belong to your account or is inaccessible. |
Failed to fetch app details. | The app ID is invalid or app is not found. |
Failed to install the app using lambda-install-app. | Installation failed due to compatibility or other issues. |
No app package or app bundle id has been provided for lambda-uninstall-app. Please check and try again. | The uninstall command is missing the app package or bundle ID. |
Failed to uninstall the app using lambda-uninstall-app. | Uninstallation failed; app may not be installed or wrong ID. |
Multiple errors may occur based on the scenario. Understanding these errors will help you identify and resolve issues more efficiently, ensuring smooth test execution. Once the code snippets are added, the tests can be executed and will appear on the TestMu AI App Automation Dashboard.
Note: If the user had enabled any of the following capabilities in the previously installed app, they will remain available and functional in the upgraded app as well :
EnableScreenshotUnblock,EnableImageInjection,EnableVideoInjection,Network,AppProfiling,EnableWebContentsDebugging,EnableBiometricInjection.This ensures that key testing features continue to work seamlessly after the app is updated, without requiring additional configuration.
Device Posture Hooks (iOS)
Virtual Device
You can change or read the fold position of iOS foldable devices during your automation session using the setDevicePosture and getDevicePosture hooks. This is useful for testing how your app responds to posture changes mid-session.
Set Device Posture
Use setDevicePosture to change the fold position during the test. Accepted values: closed, open, book.
Python example:
driver.execute_script('lambda_executor: {"action":"setDevicePosture","arguments":{"posture":"open"}}')
# → "posture set to open"
Get Device Posture
Use getDevicePosture to read the current fold position of the device.
Python example:
driver.execute_script('lambda_executor: {"action":"getDevicePosture"}')
# → "open"
- These hooks are supported on virtual devices only.
- To set the initial posture at session start, use the
devicePosturecapability. See Appium Capabilities for details.
Next Steps
Continue with these related guides:
