
Run YAML UI tests once for multiple targets: fast agent reads UI tree, reusable flows and panes, network mocks, LLM-assisted authoring and optional self-healing.
Generate and Execute with Kotlin to Keep-green through Observation
gekko runs UI tests written once in YAML on Android, iOS and the web (Chromium, Firefox and WebKit). It is built to replace slow, hand-written UI-test suites.
https://github.com/user-attachments/assets/221b71c0-87d5-4141-b0df-c3e5ea8f4fcd
pressKey: down, assertFocused, and pressKey with until to move the focus to an element (and to find a focus trap). See TV.platform: on steps (one name or a list), do or until where the platforms differ.use:. A folder with a group.yaml makes its tests share one login: the setup flows run once, the tests follow in one session, and a failed setup skips them.panes/login.yaml: its elements (one selector, or one per platform), what proves it is shown and the actions you do on it. Tests say tap: login.submit, assertPane: login or use: login.signIn, so a renamed id is fixed in one file, not in every test. See panes.mock step answers the app's network requests from a file instead of the real backend, on Android, iOS simulators and the web: a known profile, an error, a slow answer, an empty list. Nothing changes in the app, and a test undoes every mock when it ends. See network mocks and where they work: OkHttp and HttpURLConnection on Android, URLSession on iOS simulators, every request of the page on the web. Needs gekko 1.3.0.--heal, a missing id does not fail the run: a model picks the element that fits the step's intent, and a warning lists exactly what was missing and what was used instead.How the CLI, the in-app agent, the system runner and the web bridge fit together: How gekko works.
From zero to a first passing test on an Android app. You need adb and a running emulator or device (API 24 or newer).
Install the CLI (macOS arm64, Linux x64 or Windows x64) and put ~/.local/bin on your PATH:
curl -fsSL https://raw.githubusercontent.com/jakala-germany/gekko/1.4.0/scripts/install.sh | bash -s -- 1.4.0
gekko --versionOn Windows run this in PowerShell instead; it installs to %USERPROFILE%\.gekko\bin and adds that folder to your PATH, so open a new terminal afterwards. In Git Bash the curl ... | bash command above works too and hands over to install.ps1:
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/jakala-germany/gekko/1.4.0/scripts/install.ps1))) -Version 1.4.0
gekko --versionAdd the agent to the debug build. In the app module (mavenCentral() must be in the pluginManagement and dependencyResolutionManagement repositories of settings.gradle.kts):
plugins { id("io.github.jakala-germany.gekko") version "1.4.0" }
gekko { variants.set(listOf("debug")) }Give the elements your test touches an id: the search tab Home.Tab.Search and the search field Search.Field, set with Modifier.testTag("Search.Field") in Compose or a view id.
Install the debug build on the emulator: ./gradlew installDebug.
Create ui-tests/gekko.yaml with the application id (add androidActivity when the app has several launcher activities):
app:
android: com.example.appLook at the app from ui-tests/. launch prints ok once the agent answers, tree lists the ids on screen:
gekko launch --fresh
gekko treeWrite ui-tests/tests/first.yaml:
name: Search is reachable
steps:
- say: Open the search
do: { tap: { id: Home.Tab.Search } }
- say: The search field is shown
do: { assertVisible: { id: Search.Field } }Run it: gekko check && gekko run
ui-tests/ can also be a repository of its own, which is what the CI templates expect.
The gekko-setup skill does steps 2, 4 and 5 for you and checks the result (see Setting up an app).
iOS app? Steps 2 and 4 are Android only. Instead:
Build a Debug simulator app (a .app).
In gekko.yaml set app.ios (the bundle id) and ios.agentFramework: installed.
Give the elements an .accessibilityIdentifier(...) with the same strings as in step 3.
Install and look at the app on a booted simulator. A simulator UDID after -s selects iOS by itself; without -s add --platform ios:
gekko install --platform ios App.app
gekko launch --platform ios --fresh
gekko tree --platform iosRun the tests with gekko run --platform ios.
Details: iOS app in the gekko-setup skill.
Web app? Nothing goes into the app, so steps 2 and 4 are not needed. Needs gekko 1.2.0. Instead:
Install Playwright and a browser once (needs Node.js 18 or newer): gekko install -s firefox.
In gekko.yaml set app.web (the URL of the app).
Give the elements a data-testid with the same strings as in step 3.
Look at the app. A browser name after -s (chromium, firefox, webkit) selects the web by itself:
gekko launch -s firefox --fresh
gekko tree -s firefoxRun the tests with gekko run -s firefox.
Details: Web app in the gekko-setup skill.
name: Search
tags: [smoke]
steps:
- say: Complete the onboarding # the tester's intent; stays stable
do: { use: onboarding-complete } # reusable flow, named feature-screen-functionality
- say: Search for a term
do: { type: { id: Search.Field, value: gekko } }
- say: Open the first result
do: { tap: { id: Search.Result.0 } }
until: { assertVisible: { id: Detail.Title } } # repeat the tap if it was swallowed
attempts: 4
- say: Check that sharing is offered
platform: android
do: { assertVisible: { id: Detail.Share.Button } }say is the intent in the tester's words; do is exactly one action.until is the state the step must reach, attempts repeats do and until.platform: limits a step to a platform (android, ios, web or a list); ids can be shared or { android: a, ios: b, web: c }.group.yaml is a group: its setup: flows (a login) run once and its tests share that session. Needs gekko 1.2.0.An id that is copied into thirty tests breaks thirty tests. A pane writes a screen once, with its elements, what proves it is shown and the actions you do on it; tests refer to it by name.
# panes/login.yaml
identity: [title, email] # all visible: the login is on screen
elements:
title: { id: Login.Title }
email: { id: Login.Email }
submit: # one selector per platform, where they differ
android: { id: login_submit }
ios: { text: "Sign in" }
actions:
signIn:
params: [user]
steps:
- say: Enter the user
do: { type: { element: email, value: "${user}" } }
- say: Submit
do: { tap: submit }# tests/login.yaml
steps:
- say: Sign in with the test account # waits for the login pane first
do: { use: login.signIn, with: { user: "${env.TEST_USER}" } }
- say: The home screen is shown
do: { assertPane: home }A renamed id is fixed in one file. gekko check names an unknown element with a hint and warns about elements nothing uses; a failed step says which element it was and which pane is on screen; gekko tree marks the elements it knows. Needs gekko 1.3.0.
Every action, selector, variable and the rules of the format: Test and flow format.
gekko devices # adb serials, booted simulators and running web sessions
gekko tree # what is on screen (ids, texts, actions, pane elements)
gekko check # read all tests, flows and panes, no device needed
gekko run # every test on the attached device
gekko run --tags smoke --junit out.xml # tagged tests only, with a JUnit file
gekko run -s firefox # a web app in a browser
gekko run --heal claude # let a model fill in for missing idsgekko run exits with 0 when all tests passed, 1 when a test failed, 2 on a usage, YAML, configuration or version problem and 3 on a device, agent or runner problem or an app crash. A failed test leaves screenshot.png, tree.txt and failure.json in gekko-results/<test>/.
All commands, flags, exit codes, gekko.yaml and environment variables: CLI reference. Several devices and shards: How gekko works.
--heal always names where the model comes from: claude (the local CLI, the tester's own subscription), opencode or api (an OpenAI-compatible endpoint, for CI).tap, type or scroll step; the kind of the step never changes and typed text always comes from the test. Without --heal a missing element fails and nothing is guessed.gekko-heal-report.md. --junit-healed writes a second JUnit file with one failed testcase per healed step, which the CI templates publish as a separate check that never fails the job.Sources, rules and the CI setup: Heal in the CLI reference.
| Android | iOS | Web |
|---|---|---|
![]() |
![]() |
![]() |
mock steps; gekko { networkMocks.set(false) } switches that off).GekkoAgent.framework into the simulator app at launch. The settings are in the iOS note of the quick start.app.web in a browser it controls through Playwright and injects a script that only reads the page. Elements are named by data-testid (or flt-semantics-identifier for Flutter web), text and accessible labels. The settings are in the web note of the quick start and the web: keys of the CLI reference.gekko-setup wires an Android app, an iOS app, a web app or a test repo (including CI workflows); gekko-author is the daily loop for writing and repairing tests with Claude.Step by step with the checks: gekko-setup.
jakala-germany/setup-gekko-cli-action (its tag is the gekko version) installs the CLI and the runners from the release, puts gekko on the PATH and removes everything when the job is done. Pin it to the commit of its tag:
- uses: jakala-germany/setup-gekko-cli-action@36773c689902f11f16f22e1d6c3842e26d4cfe19 # 1.4.0
with:
version: 1.4.0
ios: true # also the iOS runner and agent (macOS runners)
# web needs only Node.js, see the CLI reference
- run: gekko run --tags smokeWorkflow templates for pull requests, nightly runs and an app repository are in skills/gekko-setup/assets/workflows/. Web tests need no emulator, only Node.js on the runner. Details and a web job: In CI in the CLI reference.
--heal api uses curl (Windows 10 and newer ship it). On Windows ~/.gekko is %USERPROFILE%\.gekko.adb (on Windows the platform-tools of the Android SDK on your PATH); the agent needs minSdk 21, the emulator or device that runs the tests API 24 (Android 7.0) or newer.gekko install --platform web downloads Playwright and the browsers (on Linux CI add --with-deps).gekko.yaml, the CLI and the Gradle plugin; details in the CLI reference.env: in gekko.yaml), never in test files. Add .env and gekko-results*/ to .gitignore.How the command servers are protected and how to report a vulnerability: SECURITY.md.
Build, test and repository layout are in CONTRIBUTING.md, releases in RELEASE.md and changes in CHANGELOG.md.
Apache License 2.0, see LICENSE.
Generate and Execute with Kotlin to Keep-green through Observation
gekko runs UI tests written once in YAML on Android, iOS and the web (Chromium, Firefox and WebKit). It is built to replace slow, hand-written UI-test suites.
https://github.com/user-attachments/assets/221b71c0-87d5-4141-b0df-c3e5ea8f4fcd
pressKey: down, assertFocused, and pressKey with until to move the focus to an element (and to find a focus trap). See TV.platform: on steps (one name or a list), do or until where the platforms differ.use:. A folder with a group.yaml makes its tests share one login: the setup flows run once, the tests follow in one session, and a failed setup skips them.panes/login.yaml: its elements (one selector, or one per platform), what proves it is shown and the actions you do on it. Tests say tap: login.submit, assertPane: login or use: login.signIn, so a renamed id is fixed in one file, not in every test. See panes.mock step answers the app's network requests from a file instead of the real backend, on Android, iOS simulators and the web: a known profile, an error, a slow answer, an empty list. Nothing changes in the app, and a test undoes every mock when it ends. See network mocks and where they work: OkHttp and HttpURLConnection on Android, URLSession on iOS simulators, every request of the page on the web. Needs gekko 1.3.0.--heal, a missing id does not fail the run: a model picks the element that fits the step's intent, and a warning lists exactly what was missing and what was used instead.How the CLI, the in-app agent, the system runner and the web bridge fit together: How gekko works.
From zero to a first passing test on an Android app. You need adb and a running emulator or device (API 24 or newer).
Install the CLI (macOS arm64, Linux x64 or Windows x64) and put ~/.local/bin on your PATH:
curl -fsSL https://raw.githubusercontent.com/jakala-germany/gekko/1.4.0/scripts/install.sh | bash -s -- 1.4.0
gekko --versionOn Windows run this in PowerShell instead; it installs to %USERPROFILE%\.gekko\bin and adds that folder to your PATH, so open a new terminal afterwards. In Git Bash the curl ... | bash command above works too and hands over to install.ps1:
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/jakala-germany/gekko/1.4.0/scripts/install.ps1))) -Version 1.4.0
gekko --versionAdd the agent to the debug build. In the app module (mavenCentral() must be in the pluginManagement and dependencyResolutionManagement repositories of settings.gradle.kts):
plugins { id("io.github.jakala-germany.gekko") version "1.4.0" }
gekko { variants.set(listOf("debug")) }Give the elements your test touches an id: the search tab Home.Tab.Search and the search field Search.Field, set with Modifier.testTag("Search.Field") in Compose or a view id.
Install the debug build on the emulator: ./gradlew installDebug.
Create ui-tests/gekko.yaml with the application id (add androidActivity when the app has several launcher activities):
app:
android: com.example.appLook at the app from ui-tests/. launch prints ok once the agent answers, tree lists the ids on screen:
gekko launch --fresh
gekko treeWrite ui-tests/tests/first.yaml:
name: Search is reachable
steps:
- say: Open the search
do: { tap: { id: Home.Tab.Search } }
- say: The search field is shown
do: { assertVisible: { id: Search.Field } }Run it: gekko check && gekko run
ui-tests/ can also be a repository of its own, which is what the CI templates expect.
The gekko-setup skill does steps 2, 4 and 5 for you and checks the result (see Setting up an app).
iOS app? Steps 2 and 4 are Android only. Instead:
Build a Debug simulator app (a .app).
In gekko.yaml set app.ios (the bundle id) and ios.agentFramework: installed.
Give the elements an .accessibilityIdentifier(...) with the same strings as in step 3.
Install and look at the app on a booted simulator. A simulator UDID after -s selects iOS by itself; without -s add --platform ios:
gekko install --platform ios App.app
gekko launch --platform ios --fresh
gekko tree --platform iosRun the tests with gekko run --platform ios.
Details: iOS app in the gekko-setup skill.
Web app? Nothing goes into the app, so steps 2 and 4 are not needed. Needs gekko 1.2.0. Instead:
Install Playwright and a browser once (needs Node.js 18 or newer): gekko install -s firefox.
In gekko.yaml set app.web (the URL of the app).
Give the elements a data-testid with the same strings as in step 3.
Look at the app. A browser name after -s (chromium, firefox, webkit) selects the web by itself:
gekko launch -s firefox --fresh
gekko tree -s firefoxRun the tests with gekko run -s firefox.
Details: Web app in the gekko-setup skill.
name: Search
tags: [smoke]
steps:
- say: Complete the onboarding # the tester's intent; stays stable
do: { use: onboarding-complete } # reusable flow, named feature-screen-functionality
- say: Search for a term
do: { type: { id: Search.Field, value: gekko } }
- say: Open the first result
do: { tap: { id: Search.Result.0 } }
until: { assertVisible: { id: Detail.Title } } # repeat the tap if it was swallowed
attempts: 4
- say: Check that sharing is offered
platform: android
do: { assertVisible: { id: Detail.Share.Button } }say is the intent in the tester's words; do is exactly one action.until is the state the step must reach, attempts repeats do and until.platform: limits a step to a platform (android, ios, web or a list); ids can be shared or { android: a, ios: b, web: c }.group.yaml is a group: its setup: flows (a login) run once and its tests share that session. Needs gekko 1.2.0.An id that is copied into thirty tests breaks thirty tests. A pane writes a screen once, with its elements, what proves it is shown and the actions you do on it; tests refer to it by name.
# panes/login.yaml
identity: [title, email] # all visible: the login is on screen
elements:
title: { id: Login.Title }
email: { id: Login.Email }
submit: # one selector per platform, where they differ
android: { id: login_submit }
ios: { text: "Sign in" }
actions:
signIn:
params: [user]
steps:
- say: Enter the user
do: { type: { element: email, value: "${user}" } }
- say: Submit
do: { tap: submit }# tests/login.yaml
steps:
- say: Sign in with the test account # waits for the login pane first
do: { use: login.signIn, with: { user: "${env.TEST_USER}" } }
- say: The home screen is shown
do: { assertPane: home }A renamed id is fixed in one file. gekko check names an unknown element with a hint and warns about elements nothing uses; a failed step says which element it was and which pane is on screen; gekko tree marks the elements it knows. Needs gekko 1.3.0.
Every action, selector, variable and the rules of the format: Test and flow format.
gekko devices # adb serials, booted simulators and running web sessions
gekko tree # what is on screen (ids, texts, actions, pane elements)
gekko check # read all tests, flows and panes, no device needed
gekko run # every test on the attached device
gekko run --tags smoke --junit out.xml # tagged tests only, with a JUnit file
gekko run -s firefox # a web app in a browser
gekko run --heal claude # let a model fill in for missing idsgekko run exits with 0 when all tests passed, 1 when a test failed, 2 on a usage, YAML, configuration or version problem and 3 on a device, agent or runner problem or an app crash. A failed test leaves screenshot.png, tree.txt and failure.json in gekko-results/<test>/.
All commands, flags, exit codes, gekko.yaml and environment variables: CLI reference. Several devices and shards: How gekko works.
--heal always names where the model comes from: claude (the local CLI, the tester's own subscription), opencode or api (an OpenAI-compatible endpoint, for CI).tap, type or scroll step; the kind of the step never changes and typed text always comes from the test. Without --heal a missing element fails and nothing is guessed.gekko-heal-report.md. --junit-healed writes a second JUnit file with one failed testcase per healed step, which the CI templates publish as a separate check that never fails the job.Sources, rules and the CI setup: Heal in the CLI reference.
| Android | iOS | Web |
|---|---|---|
![]() |
![]() |
![]() |
mock steps; gekko { networkMocks.set(false) } switches that off).GekkoAgent.framework into the simulator app at launch. The settings are in the iOS note of the quick start.app.web in a browser it controls through Playwright and injects a script that only reads the page. Elements are named by data-testid (or flt-semantics-identifier for Flutter web), text and accessible labels. The settings are in the web note of the quick start and the web: keys of the CLI reference.gekko-setup wires an Android app, an iOS app, a web app or a test repo (including CI workflows); gekko-author is the daily loop for writing and repairing tests with Claude.Step by step with the checks: gekko-setup.
jakala-germany/setup-gekko-cli-action (its tag is the gekko version) installs the CLI and the runners from the release, puts gekko on the PATH and removes everything when the job is done. Pin it to the commit of its tag:
- uses: jakala-germany/setup-gekko-cli-action@36773c689902f11f16f22e1d6c3842e26d4cfe19 # 1.4.0
with:
version: 1.4.0
ios: true # also the iOS runner and agent (macOS runners)
# web needs only Node.js, see the CLI reference
- run: gekko run --tags smokeWorkflow templates for pull requests, nightly runs and an app repository are in skills/gekko-setup/assets/workflows/. Web tests need no emulator, only Node.js on the runner. Details and a web job: In CI in the CLI reference.
--heal api uses curl (Windows 10 and newer ship it). On Windows ~/.gekko is %USERPROFILE%\.gekko.adb (on Windows the platform-tools of the Android SDK on your PATH); the agent needs minSdk 21, the emulator or device that runs the tests API 24 (Android 7.0) or newer.gekko install --platform web downloads Playwright and the browsers (on Linux CI add --with-deps).gekko.yaml, the CLI and the Gradle plugin; details in the CLI reference.env: in gekko.yaml), never in test files. Add .env and gekko-results*/ to .gitignore.How the command servers are protected and how to report a vulnerability: SECURITY.md.
Build, test and repository layout are in CONTRIBUTING.md, releases in RELEASE.md and changes in CHANGELOG.md.
Apache License 2.0, see LICENSE.