| title | description | icon |
|---|---|---|
API Reference |
Python library API reference |
gear-code |
To Initialize a python client for camelQA, you must pass in an API key and optional parameters. Note that parameters differ based on implementation.
```swift // Set the bundle ID of the app you'd like to test let app = XCUIApplication(bundleIdentifier: "com.toyopagroup.picaboo") app.launch() let q = QamlClient(
apiKey: "<API_KEY>",
app: "<APP_INSTANCE>",
useAccessibilityElements: <BOOL, default = true>
)
```
#### app
This is the [bundleID](https://offcornerdev.com/bundleid.html) of the app you'd like to launch. **Note** you can still switch between apps by using switchToApp or openURL.
#### useAccessibilityElements
Tests executed in XCUITest can utilize accessibility labels. Setting this to true leverages accessibility elements. Setting this to false uses pure vision.
</Tab>
<Tab title="Android">
<CodeGroup>
```java Java
@Test
public void newTest() {
Client q = new Client(
"<APIKey>",
useAccessibilityElements = <BOOL, default = true>
)
}
```
```kotlin Kotlin
@Test
fun newTest() {
val q = QamlClient(
apiKey = "<APIKey>",
useAccessibilityElements = <BOOL, default = true>
)
}
```
</CodeGroup>
#### useAccessibilityElements
Tests executed in Android Studio can utilize accessibility labels. Setting this to true leverages accessibility elements. Setting this to false uses pure vision.
</Tab>
<Tab title="Appium">
```python
q = qaml.Client(
api_key="<API_KEY>",
driver=optional_appium_driver, #optional
use_mjpeg=optional_boolean, #optional, default=True
use_hid_typing=optional_boolean #optional, default=False
)
```
#### driver
This is the Appium driver instance you can use to specify your UDID for your device or simulator. This can also be used to connect to a device farm.
Tip:
```bash
xcrun simctl list devices | grep 'Booted'
```
This command gives you a list of UDIDs of all simulators currently running.
#### use_mjpeg
This flag tells qaml to use `mjpeg_consumer` if it is installed. This will speed up the time it takes to capture a screenshot, but is slightly resource intensive. If you have issues, try turning setting this to False.
#### use_hid_typing
This is an experimental feature to extend typing compatibility. This is for apps where typing is not supported by Appium. This flag simulates a USB keyboard. This is slow and only works with latin characters and numbers.
Please let us know in our Discord how this feature works for your app.
</Tab>
This is the main way you interact with qaml. Give a natural language command and it will execute the command.
Optionally, you can provide a count to repeat the action a certain amount of times.
```swift iOS q.execute("swipe down", count: 4) q.execute("tap the search bar") ``````kotlin Kotlin
q.execute("swipe up", count = 4)
q.execute("tap the search bar")
```
```java Java
q.execute("swipe up", count = 4);
q.execute("tap the search bar");
```
```python Appium
q.execute("swipe up")
q.execute("swipe down")
```
Nothing is returned. A QAMLExecException will be thrown if it is unable to execute the command.
This is how you tell qaml to verify something without taking any action. assert_condition takes a screenshot of the current screen and runs it through GPT-4o against your prompt and returns a pass or fail.
Android: Apps with FLAG_SECURE enabled block screenshots. If this occurs, camelQA falls back to using accessibility labels, which means visual cues are not supported. Check out this section of our prompt guide for tips on writing conditions not dependent on vision
- SpotifyKnow of any others? Please support the community by reporting them to our team.
```kotlin Kotlin
q.execute("type camelqa.com")
q.assert_condition("camelqa.com is shown")
q.execute("tap go")
q.assert_condition("loading screen is shown")
```
```java Java
q.execute("type camelqa.com");
q.assert_condition("camelqa.com is shown");
q.execute("tap go");
q.assert_condition("loading screen is shown");
```
```python Appium
q.execute("type camelqa.com")
q.assert_condition("camelqa.com is shown")
q.execute("tap go")
q.assert_condition("loading screen is shown")
```
Nothing is returned. A QAMLExecException will be thrown if the condition is not met.
This calls assert_condition on a loop. This is how you tell qaml to wait until an event occurs (ex. screen has completed loading).
waitUntil takes a screenshot of the current screen and runs it through GPT-4o against your prompt and returns a pass or fail until the condition is met or timeout occurs.
Android: Apps with FLAG_SECURE enabled block screenshots. If this occurs, camelQA falls back to using accessibility labels, which means visual cues are not supported. Check out this section of our prompt guide for tips on writing conditions not dependent on vision
- SpotifyKnow of any others? Please support the community by reporting them to our team.
// example:
q.waitUntil("Results page has completed loading", timeout: 20)
```
```kotlin Kotlin
q.waitUntil(
condition: <String>,
timeout: <TimeInterval> // optional, specify in seconds, default is 10 seconds
)
// example:
q.waitUntil("Results page has completed loading", timeout = 20.0)
```
```java Java
q.waitUntil(
condition: <String>,
timeout: <TimeInterval> // optional, specify in seconds, default is 10 seconds
);
// example:
q.waitUntil("Results page has completed loading", timeout = 20.0);
```
```python Appium
# not supported in python at this time
```
This appends information to the qaml system prompt. Use this to specify details about your app.
```swift iOS // qaml can't tell what a liked image looks like on Instagram. This system prompt solves the issue q.systemPrompt = "An image is like if the heart icon is solid is red. An image is not liked if the heart icon is a white outline and not filled." ``````kotlin Kotlin
// qaml can't tell what a liked image looks like on Instagram. This system prompt solves the issue
q.systemPrompt = "An image is like if the heart icon is solid is red. An image is not liked if the heart icon is a white outline and not filled."
```
```java Java
// qaml can't tell what a liked image looks like on Instagram. This system prompt solves the issue
q.setSystemPrompt("An image is like if the heart icon is solid is red. An image is not liked if the heart icon is a white outline and not filled.");
```
```python Appium
# qaml can't tell what a liked image looks like on Instagram. This system prompt solves the issue
q.system_prompt = "An image is like if the heart icon is solid is red. An image is not liked if the heart icon is a white outline and not filled."
```
This adds a delay between each command. Use this if your app has long animations or you want to add a delay between each action. By default, this value is 0.
autoDelay is set at the client level and is synchronous, as in it only affects the code after the statement. This means you can switch this value throughout your test script. If you re-initialize the client, it is reset to zero.
Note, this is purely additive. This does not guarantee that the delay between each step will be exactly the time specified; it simply ensures that there will be a time delay before an action begins.
```swift iOS q.autoDelay = // specify in seconds, takes a floating point// example:
q.autoDelay = 20.0
```
```kotlin Kotlin
q.autoDelay = <TimeInterval> // specify in seconds, takes a floating point
// example:
q.autoDelay = 20.0
```
```java Java
q.setAutoDelay(<TimeInterval>); // specify in seconds, takes a floating point
// example:
q.autoDelay(20.0);
```
```python Appium
# not supported at this time
```
This is how to switch between apps. For iOS, use the bundleID. For Android, use the package ID.
Note: for iOS, you must switch to an app using this function in order to interact with that app.
```swift iOS q.switchToApp(bundleId: "com.apple.mobilesafari") ``` ```kotlin Kotlin q.switchToApp(packageName = "com.google.android.youtube")```
```java Java
q.switchToApp(packageName = "com.google.android.youtube");
```
```python Appium
# use bundleID or package
q.switch_to_app("com.apple.mobilesafari")
```
This is how to hard launch apps. This will kill the app and restart it. For iOS, use the bundleID. For Android, use the package ID.
```swift iOS q.launchApp(bundleId: "com.apple.mobilesafari") ``````kotlin Kotlin
q.launchApp(packageName = "com.google.android.youtube")
```
```java Java
q.launchApp(packageName = "com.google.android.youtube");
```
```python Appium
# not supported at this time
```
This is how to open a deeplink to your app or a URL on the default web browser.
Be sure to include https:// in your URL or your custom URL scheme for deeplinking.
Note: Requires XCode 14.3 and higher and iOS 16 and higher
```swift iOS // in order to interact with the URL, you must launch the web browser or use q.switchToApp() let app = XCUIApplication(bundleIdentifier: "com.apple.mobilesafari") app.launch()q.openURL(url: "https://en.m.wikipedia.org/wiki/Artificial_intelligence")
```
```kotlin Kotlin
q.openURL(urlString = "https://google.com")
```
```java Java
q.openURL(urlString = "https://google.com");
```
```python Appium
# not supported in python at this time
```
This is how to scroll in a specific direction or to a specific element. Directions available are up, down, left, and right.
```swift iOS q.scroll(direction: , until: )// example:
q.scroll(direction: .down, until: "'Logout' button is visible")
```
```kotlin Kotlin
q.scroll(direction: Direction, untilCondition: String)
// example:
q.scroll(Client.Direction.DOWN, "'Logout' button is visible")
```
```java Java
q.scroll(direction: Direction, untilCondition: String);
// example:
q.scroll(Client.Direction.DOWN, "'Logout' button is visible");
```
```python Appium
# not supported in python at this time
```
This is how to retrieve a value from the app. This returns a string.
There are two modes you can use, screen shot and element list.
Screen shot uses vision to parse out the information you requested. This is a smarter model and capable of more complex asks. However, this is slower and does not have access to element labels or IDs.
Element list does not use vision. It is a simpler model that parses the element list to return the value you've requested. This is faster than screen shot mode and can access element labels and IDs.
```swift iOS q.launchApp("com.apple.weather")let weatherDescription = q.getValue(searchFor: "The high tomorrow", mode: .screenShot)
```
```kotlin Kotlin
q.switchToApp("com.weather.Weather")
val weatherDescription = q.getValue("get the 'feels like' temperature", Client.SearchMode.SCREENSHOT)
```
```java Java
q.switchToApp("com.weather.Weather");
String weatherDescription = q.getValue("get the 'feels like' temperature", Client.SearchMode.SCREENSHOT);
```
```python Appium
# not supported in python at this time
```
This is how to handle system alerts automatically.
Note, iOS handles alerts across all applications. Android only handles the alerts of the target app.
```swift iOS // By default the handler is on and accepts all permissions.// To set a custom alert handler set the alertHandler property on the qaml client object:
q.alertHandler = "Accept all permissions except for location"
// To disable this feature completely, set the alertHandler property to nil:
q.alertHandler = nil ```
```kotlin Kotlin
// add QamlTest() to the declaration of the test suite
class PermissionsTest: QamlTest() {
// all tests defined within the test suite will auto accept system pop ups
@Test
fun testWithPermissions() {
...
}
...
}
```
```java Java
// Add QamlTest() to the declaration of the test suite
public class PermissionsTest extends QamlTest {
// All tests defined within the test suite will auto accept system pop ups
@Test
public void testWithPermissions() {
...
}
...
}
```
```python Appium
# not supported in python at this time
```
This will dump all accessibility elements for the current screen to the console. This is used for debugging and does not perform any actions.
```swift iOS q.dumpAccessibilityElements() ``````kotlin Kotlin
q.dumpAccessibilityElements()
```
```java Java
q.dumpAccessibilityElements();
```
```python Appium
# not supported in python at this time
```