add getting started examples for LLM for Android and iOS

small fixes in android LLM locator logic

Author: angelovstanton

src/Bellatrix.Mobile/llm/android/FindByPrompt.cs

@@ -170,6 +170,7 @@ private string ResolveViaPromptFallback(string location, object context, int max
 
             var result = SemanticKernelService.Kernel.InvokePromptAsync(prompt).Result;
             var rawSelector = result?.GetValue<string>()?.Trim();
+            rawSelector = ParsePromptLocatorToUIAutomator(rawSelector);
 
             if (string.IsNullOrWhiteSpace(rawSelector))
                 continue;

src/Bellatrix.Mobile/llm/android/skills/AndroidLocatorSkill.cs

@@ -30,9 +30,9 @@ public string BuildLocatorPrompt(string viewSummaryJson, string instruction, Lis
             : "(none)";
 
         return $"""
-You are an AI assistant helping with Android mobile UI test automation using Appium.
+You are an AI assistant for Android UI test automation using Appium.
 
-Your task is to generate a valid, reliable **Android UIAutomator locator** that will scroll to and find the element based on:
+Your task is to generate a **valid UiAutomator selector string** for locating an Android element based on:
 - A user instruction
 - A structured snapshot of visible elements (JSON)
 - A list of previously failed selectors
@@ -50,43 +50,51 @@ public string BuildLocatorPrompt(string viewSummaryJson, string instruction, Lis
 
 ---
 
-✅ Return a **UiSelector** expression inside **UiScrollable** to scroll to the element:
-- textContains("...")
-- descriptionContains("...")
-- className("...")
-- resourceIdMatches(".*value.*")
+**UiAutomator Selector Rules (Strict):**
 
-✅ Format Examples:
-- uiautomator=new UiScrollable(new UiSelector()).scrollIntoView(new UiSelector().textContains("Login"))
-- uiautomator=new UiScrollable(new UiSelector()).scrollIntoView(new UiSelector().descriptionContains("Settings"))
-- uiautomator=new UiScrollable(new UiSelector()).scrollIntoView(new UiSelector().resourceIdMatches(".*submit.*"))
-- uiautomator=new UiScrollable(new UiSelector()).scrollIntoView(new UiSelector().className("android.widget.Button"))
+✅ Return only one of the following as a single line:
+- new UiSelector().text("Login")
+- new UiSelector().textContains("Settings")
+- new UiSelector().description("Save")
+- new UiSelector().descriptionContains("Edit")
+- new UiSelector().resourceId("com.example:id/button")
+- new UiSelector().className("android.widget.CheckBox")
+- new UiScrollable(new UiSelector().scrollable(true)).scrollIntoView(new UiSelector().text("Submit"))
+
+✅ If scrolling is needed, use:
+- new UiScrollable(new UiSelector().scrollable(true)).scrollIntoView(new UiSelector().text("..."))
 
 🚫 Do NOT use:
+- Any `uiautomator=` prefix
+- Any `=` between selectors
 - XPath locators
-- Multiple expressions or fallback options
-- Explanations or comments
+- Explanations, comments, markdown, or code blocks
+- Multiple selectors, only a single valid one
 
 ---
 
-**Return Format:**
-Only return a single line like:
-uiautomator=new UiScrollable(new UiSelector()).scrollIntoView(new UiSelector().textContains("Login"))
+**Return Format:**  
+Return ONLY the UiAutomator selector string as a single line.  
+For example:
+- new UiSelector().text("Login")
+- new UiScrollable(new UiSelector().scrollable(true)).scrollIntoView(new UiSelector().className("android.widget.CheckBox"))
 
-Do not include anything else.
+Return nothing else.
 """;
     }
 
     [KernelFunction]
     public string HealBrokenLocator(string failedLocator, string oldSnapshot, string newSnapshot)
     {
         return $"""
-You are an AI assistant helping to fix broken Android locators for Appium tests.
+You are an AI assistant for fixing broken Android UI locators for Appium.
 
-The original locator failed:
+The original UiAutomator locator failed:
 ❌ Failed: {failedLocator}
 
-Your job is to return a **new valid uiautomator locator** using the updated view snapshot.
+Your task is to generate a **new valid UiAutomator selector string** based on:
+- A previously working view summary (JSON)
+- A new view snapshot after the failure
 
 ---
 
@@ -98,17 +106,24 @@ public string HealBrokenLocator(string failedLocator, string oldSnapshot, string
 
 ---
 
-✅ Guidelines:
-- Use UiScrollable + UiSelector syntax
-- Prefer textContains, descriptionContains, resourceIdMatches
-- One clean line, no explanations
+**Guidelines:**
 
----
+✅ Use ONLY UiSelector or UiScrollable + UiSelector, e.g.:
+- new UiSelector().text("Login")
+- new UiScrollable(new UiSelector().scrollable(true)).scrollIntoView(new UiSelector().descriptionContains("Settings"))
 
-**Output Format Example:**
-uiautomator=new UiScrollable(new UiSelector()).scrollIntoView(new UiSelector().textContains("Login"))
+🚫 Do NOT use:
+- Any `uiautomator=` prefix
+- XPath selectors
+- Comments, explanations, markdown, or code blocks
+
+---
 
-Return ONLY a single locator line.
+**Output Format:**  
+Return ONLY the new UiAutomator selector as a single line, nothing else.
+For example:
+- new UiSelector().text("Submit")
+- new UiScrollable(new UiSelector().scrollable(true)).scrollIntoView(new UiSelector().textContains("Continue"))
 """;
     }
 }

templates/Bellatrix.Android.GettingStarted/32. Prompts Support/MainPage/MainAndroidPage.Actions.cs

@@ -0,0 +1,34 @@
+using Bellatrix.Mobile.PageObjects;
+using Bellatrix.Mobile.Services.Android;
+
+namespace Bellatrix.Mobile.Android.GettingStarted.LLM;
+
+// 1. All BELLATRIX page objects are implemented as partial classes which means that you have separate files for different parts of it- actions, elements, assertions
+// but at the end, they are all built into a single type. This makes the maintainability and readability of these classes much better. Also, you can easier locate what you need.
+//
+// You can always create BELLATRIX page objects yourself inherit AndroidPage
+// We advise you to follow the convention with partial classes, but you are always free to put all pieces in a single file.
+public partial class MainAndroidPage : AndroidPage
+{
+    private AndroidKeyboardService _keyboardService;
+
+    public MainAndroidPage(AndroidKeyboardService androidKeyboardService) => _keyboardService = androidKeyboardService;
+
+    // 2. These elements are always used together when an item is transferred. There are many test cases where you need to transfer different items and so on.
+    // This way you reuse the code instead of copy-paste it. If there is a change in the way how the item is transferred, change the workflow only here.
+    // Even single line of code is changed in your tests.
+    public void TransferItem(string itemToBeTransferred, string userName, string password)
+    {
+        _keyboardService.HideKeyboard();
+        PermanentTransfer.Check();
+        Items.SelectByText(itemToBeTransferred);
+        ReturnItemAfter.ToExists().WaitToBe();
+        UserName.SetText(userName);
+        Password.SetPassword(password);
+        KeepMeLogged.Click();
+        Transfer.Click();
+    }
+
+    protected override string ActivityName => ".view.Controls1";
+    protected override string PackageName => Constants.AndroidNativeAppId;
+}

templates/Bellatrix.Android.GettingStarted/32. Prompts Support/MainPage/MainAndroidPage.Assertions.cs

@@ -0,0 +1,24 @@
+namespace Bellatrix.Mobile.Android.GettingStarted.LLM;
+
+public partial class MainAndroidPage
+{
+    public void AssertPermanentTransferIsChecked()
+    {
+        App.Assert.IsTrue(PermanentTransfer.IsChecked);
+    }
+
+    public void AssertRightItemSelected(string itemName)
+    {
+        App.Assert.AreEqual(itemName, Items.GetText());
+    }
+
+    public void AssertRightUserNameSet(string userName)
+    {
+        App.Assert.AreEqual(userName, UserName.GetText());
+    }
+
+    public void AssertKeepMeLoggedChecked()
+    {
+        App.Assert.IsTrue(KeepMeLogged.IsChecked);
+    }
+}

templates/Bellatrix.Android.GettingStarted/32. Prompts Support/MainPage/MainAndroidPage.Map.cs

@@ -0,0 +1,17 @@
+namespace Bellatrix.Mobile.Android.GettingStarted.LLM;
+
+public partial class MainAndroidPage
+{
+    // 1. All elements are placed inside the file PageName.Map so that the declarations of your elements to be in a single place.
+    // It is convenient since if there is a change in some of the locators or elements types you can apply the fix only here.
+    // All elements are implements as properties. Here we use the short syntax for declaring properties, but you can always use the old one.
+    // App.Components property is actually a shorter version of ComponentCreateService
+    public Button Transfer => App.Components.CreateByIdContaining<Button>("button");
+    public CheckBox PermanentTransfer => App.Components.CreateByIdContaining<CheckBox>("check1");
+    public ComboBox Items => App.Components.CreateByIdContaining<ComboBox>("spinner1");
+    public Button ReturnItemAfter => App.Components.CreateByIdContaining<Button>("toggle1");
+    public Label Results => App.Components.CreateByText<Label>("textColorPrimary");
+    public Password Password => App.Components.CreateByIdContaining<Password>("edit2");
+    public TextField UserName => App.Components.CreateByIdContaining<TextField>("edit");
+    public RadioButton KeepMeLogged => App.Components.CreateByIdContaining<RadioButton>("radio2");
+}

templates/Bellatrix.Android.GettingStarted/32. Prompts Support/PageObjectsTests.cs

@@ -0,0 +1,41 @@
+using NUnit.Framework;
+using static Bellatrix.AiValidator;
+using static Bellatrix.AiAssert;
+
+namespace Bellatrix.Mobile.Android.GettingStarted.LLM;
+
+[TestFixture]
+[Android(Constants.AndroidNativeAppPath,
+    Constants.AndroidNativeAppId,
+    Constants.AndroidDefaultAndroidVersion,
+    Constants.AndroidDefaultDeviceName,
+    ".view.Controls1",
+    Lifecycle.RestartEveryTime)]
+public class PageObjectsTests : NUnit.AndroidTest
+{
+    [Test]
+    public void ActionsWithoutPageObjects_LLM()
+    {
+        var button = App.Components.CreateByIdContaining<Button>("button_disabled");
+        button.ValidateIsDisabled();
+        //var checkBox = App.Components.CreateByIdContaining<CheckBox>("check1");
+        var checkBox = App.Components.CreateByPrompt<CheckBox>("find the checkbox under the disabled button");
+        checkBox.Check();
+        checkBox.ValidateIsChecked();
+        var comboBox = App.Components.CreateByIdContaining<ComboBox>("spinner1");
+        comboBox.SelectByText("Jupiter");
+        comboBox.ValidateTextIs("Jupiter");
+
+        ValidateByPrompt("validate that the spinner combobox has text Jupiter");
+
+        var label = App.Components.CreateByText<Label>("textColorPrimary");
+        label.ValidateIsVisible();
+        var radioButton = App.Components.CreateByIdContaining<RadioButton>("radio2");
+        radioButton.Click();
+
+        radioButton.ValidateIsChecked(timeout: 30, sleepInterval: 2);
+
+        // fail on purpose to show how smart AI analysis works
+        //radioButton.ValidateIsNotChecked(timeout: 30, sleepInterval: 2);
+    }
+}

templates/Bellatrix.Android.GettingStarted/testFrameworkSettings.Debug.json

@@ -120,12 +120,12 @@
     "qdrantMemoryDbEndpoint": "http://localhost:6333",
     "localCacheConnectionString": "env_LocalCacheConnectionString",
     "localCacheProjectName": "android_getting_started",
-    "shouldIndexPageObjects": false,
+    "shouldIndexPageObjects": true,
     "pageObjectFilesPath": "32. Prompts Support\\Pages",
     "memoryIndex": "PageObjects",
     "resetIndexEverytime": false,
     "locatorRetryAttempts": 3,
-    "validationsTimeout": 5,
+    "validationsTimeout": 15,
     "sleepInterval": 1,
     "enableSelfHealing": true,
     "enableSmartFailureAnalysis": true

templates/Bellatrix.IOS.GettingStarted/32. Prompts Support/CalculatorPage/CalculatorPage.Actions.cs

@@ -0,0 +1,21 @@
+using Bellatrix.Mobile.PageObjects;
+
+namespace Bellatrix.Mobile.IOS.GettingStarted.LLM;
+
+// 1. All BELLATRIX page objects are implemented as partial classes which means that you have separate files for different parts of it- actions, elements, assertions
+// but at the end, they are all built into a single type. This makes the maintainability and readability of these classes much better. Also, you can easier locate what you need.
+//
+// You can always create BELLATRIX page objects yourself inheriting the IOSPage class
+// We advise you to follow the convention with partial classes, but you are always free to put all pieces in a single file.
+public partial class CalculatorPage : IOSPage
+{
+    // 2. These elements are always used together when an item is transferred. There are many test cases where you need to transfer different items and so on.
+    // This way you reuse the code instead of copy-paste it. If there is a change in the way how the item is transferred, change the workflow only here.
+    // Even single line of code is changed in your tests.
+    public void Sum(int firstNumber, int secondNumber)
+    {
+        NumberOne.SetText(firstNumber.ToString());
+        NumberTwo.SetText(secondNumber.ToString());
+        Compute.Click();
+    }
+}

templates/Bellatrix.IOS.GettingStarted/32. Prompts Support/CalculatorPage/CalculatorPage.Assertions.cs

@@ -0,0 +1,11 @@
+using Bellatrix.Mobile.IOS;
+
+namespace Bellatrix.Mobile.IOS.GettingStarted.LLM;
+
+public partial class CalculatorPage
+{
+    public void AssertAnswer(int answer)
+    {
+        Answer.ValidateTextIs(answer.ToString());
+    }
+}

templates/Bellatrix.IOS.GettingStarted/32. Prompts Support/CalculatorPage/CalculatorPage.Map.cs

@@ -0,0 +1,13 @@
+namespace Bellatrix.Mobile.IOS.GettingStarted.LLM;
+
+public partial class CalculatorPage
+{
+    // 1. All elements are placed inside the file PageName.Map so that the declarations of your elements to be in a single place.
+    // It is convenient since if there is a change in some of the locators or elements types you can apply the fix only here.
+    // All elements are implements as properties. Here we use the short syntax for declaring properties, but you can always use the old one.
+    // App.Components property is actually a shorter version of ComponentCreateService
+    public Button Compute => App.Components.CreateByName<Button>("ComputeSumButton");
+    public TextField NumberOne => App.Components.CreateById<TextField>("IntegerA");
+    public TextField NumberTwo => App.Components.CreateById<TextField>("IntegerB");
+    public Label Answer => App.Components.CreateByName<Label>("Answer");
+}