| title | description | icon |
|---|---|---|
Quickstart |
Start coding in camelQA |
timer |
### Setup Xcode
<iframe
width="560"
height="315"
src="https://www.youtube.com/embed/AojmVBgShm4"
title="YouTube video player"
frameborder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowfullscreen
></iframe>
<Steps>
<Step title="Open Xcode">
Open an existing project or create a new project in Xcode.
Follow these steps if you're creating a new project.
<Accordion title="Choose App">
<Frame>
<img width="400" src="/images/create-new-xcode1.png" />
</Frame>
</Accordion>
<Accordion title="Ensure Include Tests is checked">
<Frame>
<img width="400" src="/images/create-new-xcode2.png" />
</Frame>
</Accordion>
</Step>
<Step title="Add package dependency">
In the top menu bar go to File -> Add package dependencies
</Step>
<Step title="Search for package">
In the search field in the top right corner paste https://github.com/qaml-ai/qaml-swift
</Step>
<Step title="Click add package.">
</Step>
<Step title="Select target">
Select your UITest target, NOT your main app target.
<Accordion title="Selecting UITest target">
<Frame>
<img width="400" src="/images/ios-project-target.png" />
</Frame>
</Accordion>
</Step>
</Steps>
### Writing Tests in qaml-swift
<Steps>
<Step title="Go to a test File">
</Step>
<Step title="Import qaml">
Include `import qaml` at the top of your test file
</Step>
<Step title="Create a new test function">
Note, this test case will only work if you have Apple weather app on your device.
Example test:
```swift
import XCTest
import qaml
final class test_sampleTest: XCTestCase {
func test_weatherApp_weatherInSF() throws {
let app = XCUIApplication(bundleIdentifier: "com.apple.weather")
app.launch()
let q = QamlClient(
apiKey: "<API_KEY>",
app: app
)
q.execute("click the location list button")
q.execute("tap the search bar at the top")
q.execute("type San Francisco")
q.execute("tap the first result in the location list, 'San Francisco, CA United States'")
q.assertCondition("The screen shows the weather for San Francisco")
}
}
```
</Step>
<Step title="Select your device">
Select the device you'd like to run your test on at the top.
> - For physical devices, attach your device to your computer via USB.
> - For simulated devices, select your desired device from the drop down menu.
> - For third party device farms, following their XCUITest documentation.
> - [AWS Docs](https://docs.aws.amazon.com/devicefarm/latest/developerguide/test-types-ios-xctest-ui.html), [Sauce Labs Docs](https://docs.saucelabs.com/mobile-apps/automated-testing/espresso-xcuitest/), [Browserstack Docs](https://www.browserstack.com/docs/app-automate/api-reference/xcuitest/overview).
<Note>
If you have XCode cloud set up, these tests will run as part of your Xcode cloud actions. Apple offers iOS developers 25 hours of free device farm access per month.
Read more about this on [Xcode's documentation](https://developer.apple.com/xcode-cloud/#:~:text=Apple%20Developer%20Program%20membership%20includes,Cloud%20monthly%20subscriptions%20are%20available.&text=Upgrade%20or%20downgrade%20your%20subscription%20at%20any%20time. "Xcode Cloud Subscription").
</Note>
</Step>
</Steps>
### Setup Android Studio
<iframe
width="560"
height="315"
src="https://www.youtube.com/embed/cLSZsteVpIg"
title="YouTube video player"
frameborder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowfullscreen
></iframe>
<Steps>
<Step title="Open Android Studio">
Open an existing project or create a new project. We support both Kotlin DSL and Groovy.
</Step>
<Step title="Add camelQA repo">
Add the camelQA repository to your Gradle build settings, usually `settings.gradle.kts`.
<CodeGroup>
```java Groovy/Java
pluginManagement {
repositories {
google {
content {
includeGroupByRegex("com\\.android.*")
includeGroupByRegex("com\\.google.*")
includeGroupByRegex("androidx.*")
}
}
mavenCentral()
gradlePluginPortal()
// Paste in this section
maven {
url "https://cdn.camelqa.com/"
}
}
}
dependencyResolutionManagement {
repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
repositories {
google()
mavenCentral()
// Paste in this section
maven {
url "https://cdn.camelqa.com/"
}
}
}
```
```kotlin Kotlin DSL
pluginManagement {
repositories {
google {
content {
includeGroupByRegex("com\\.android.*")
includeGroupByRegex("com\\.google.*")
includeGroupByRegex("androidx.*")
}
}
mavenCentral()
gradlePluginPortal()
// Paste in this section
maven {
url = uri("https://cdn.camelqa.com/")
}
}
}
dependencyResolutionManagement {
repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
repositories {
google()
mavenCentral()
// Paste in this section
maven {
url = uri("https://cdn.camelqa.com/")
}
}
}
```
</CodeGroup>
</Step>
<Step title="Add camelQA dependency">
Add the camelQA library dependency to the list of dependencies in your Gradle build file. The file is in Gradle Scripts > usually `build.gradle.kts (Module: app)`.
<CodeGroup>
```java Groovy/Java
dependencies {
// Add this to auto update your package
androidTestImplementation'androidx.test.uiautomator:uiautomator:2.2.0'
androidTestImplementation 'com.camelqa:qaml:latest.release'
// Alternatively, you can specify one version
androidTestImplementation 'com.camelqa:qaml:1.0.6'
}
```
```kotlin Kotlin DSL
dependencies {
// Add this to auto update your package
androidTestImplementation("androidx.test.uiautomator:uiautomator:2.2.0")
androidTestImplementation("com.camelqa:qaml:latest.release")
// Alternatively, you can specify one version
androidTestImplementation("com.camelqa:qaml:1.0.6")
}
```
</CodeGroup>
</Step>
<Step title="Enable QUERY_ALL_PACKAGES">
Add `<uses-permission android:name="android.permission.QUERY_ALL_PACKAGES"/>` to `AndriodManifest.xml` file.
This step is required to allow camelQA to switch between apps. **If you do not need to switch between apps, you may skip this step.**
```xml
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:tools="http://schemas.android.com/tools">
<uses-permission android:name="android.permission.INTERNET" />
<!-- add the line below -->
<uses-permission android:name="android.permission.QUERY_ALL_PACKAGES"/>
...
```
<Note>**This will raise a warning related to the use of the QUERY_ALL_PACKAGES permission.** The permission allows your app to see the full list of installed applications on the device. The API uses this list locally so you may switch between apps. camelQA does not recieve or store this list. Ignore the warning.</Note>
**Alternatively,** if you would like to switch between apps without surfacing the entire list of available apps on your device, you can add a `<queries>` element within the `<manifest>` element of your `AndroidManifest.xml` file.
This element allows you to specify which packages your app needs to query.
```xml
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:tools="http://schemas.android.com/tools">
<queries>
<!-- Declare specific apps your app needs to query -->
<package android:name="com.example.specificapp" />
<intent>
<action android:name="android.intent.action.VIEW" />
<data android:scheme="https" />
</intent>
</queries>
<application
android:allowBackup="true"
android:dataExtractionRules="@xml/data_extraction_rules"
android:fullBackupContent="@xml/backup_rules">
<!-- Your application components -->
</application>
</manifest>
```
</Step>
<Step title="Import qaml to your Android Instrumented Tests">
Locate the correct file. App > Kotlin+Java > com.your.package.name (androidTest)
Import qaml and create your first test. Note, `myFirstTest` requires the Youtube app to be installed.
<CodeGroup>
```java Java
import androidx.test.ext.junit.runners.AndroidJUnit4;
import org.junit.Test;
import org.junit.runner.RunWith;
// add this import to the top of your file
import com.camelqa.qaml.Client;
@RunWith(AndroidJUnit4.class)
public class ExampleInstrumentedTest {
// create a test with camelQA
@Test
public void myFirstTest() {
// replace with your API_KEY
Client q = new Client("<API_KEY>");
q.launchApp("com.google.android.youtube")
q.execute("tap the 'Shorts' tab in the bottom nav bar")
q.assertCondition("The screenshot is of a video app. It shows a video or image. The bottom section of the screen shows the video's title, the creator's username. On the right there are options to like, dislike, comment, and share.")
q.execute("tap the view comments button")
q.assertCondition("The screen shows an app with a drawer of comments open that takes up most of the screen")
q.execute("tap the close button")
}
}
```
```kotlin Kotlin
import androidx.test.ext.junit.runners.AndroidJUnit4
import org.junit.Test
import org.junit.runner.RunWith
// add this import to the top of your file
import com.camelqa.qaml.Client as QamlClient
@RunWith(AndroidJUnit4::class)
class ExampleInstrumentedTest {
// create a test with camelQA
@Test
fun myFirstTest() {
// replace with your API_KEY
val q = QamlClient(apiKey = "<API_KEY>")
q.launchApp("com.google.android.youtube")
q.execute("tap the 'Shorts' tab in the bottom nav bar")
q.assertCondition("The screenshot is of a video app. It shows a video or image. The bottom section of the screen shows the video's title, the creator's username. On the right there are options to like, dislike, comment, and share.")
q.execute("tap the view comments button")
q.assertCondition("The screen shows an app with a drawer of comments open that takes up most of the screen")
q.execute("tap the close button")
}
}
```
</CodeGroup>
</Step>
</Steps>
iOS and Adroid - Requires Appium and WebDriverAgent setup
### Setup Your Machine
<AccordionGroup>
<Accordion icon="mobile" title="Plug in a phone">
Plug in an Android or iPhone to your machine. If no devices are connected it will fallback to the iOS Simulator.
<Info>
**IMPORTANT** Ensure your device has [developer mode](https://developer.apple.com/documentation/xcode/enabling-developer-mode-on-a-device) turned on.
</Info>
</Accordion>
<Accordion icon="rectangle-terminal" title="Run Appium in your terminal">
Ensure your are running [appium](https://appium.io/docs/en/2.5/quickstart/install/) on your machine.
Use Homebrew on macOS `brew install appium` or follow the instructions linked above.
</Accordion>
<Accordion icon="rectangle-terminal" title="Ensure you have mjpeg-consumer on your machine">
Using mjpeg-consumer is optional; however, it is strongly recommended because it significantly speeds up execution.
Here's how to install `mjpeg-consumer` on your machine. Navigate to your appium directory.
```
cd `which appium`/..
```
Install `mjpeg-consumer`.
```
npm i mjpeg-consumer
```
Optionally, navigate back to your previous directory
```
cd -
```
</Accordion>
<Accordion icon="rectangle-terminal" title="Spin up your virtual environment">
Create your VE
```
python3 -m venv .venv
```
Activate your VE
```
source .venv/bin/activate
```
</Accordion>
</AccordionGroup>
### Install qaml and start controlling your device in natural language
```
pip install qaml
```
Or update the CLI with `pip install -U qaml`
Set the QAML_API_KEY environment variable to your API key
```
export QAML_API_KEY=<API_KEY>
```
Start using qaml in python or command line