Repository navigation
Releases
Releases · jakala-germany/gekko
1.4.0
Immutable
release. Only release title and notes can be modified.
New
- TV support, on Android TV / Google TV and Apple TV simulators (#38): gekko recognises a TV by itself (the leanback or television feature of an Android device, the tvOS runtime of a simulator;
gekko devicesmarks ittv) and tests it with the remote instead of touches.pressKeytakes the buttonsup,down,left,right,select,playPauseandmenu(Android key codes through the system runner, because an app cannot inject key events into its own window;XCUIRemoteon tvOS, wherebackis the menu button), the new stepassertFocused: { id: home.teaser, index: 1 }waits until that element has the focus (the index is counted first, so it is the second teaser; the failure says where the focus is), andpressKey: { key: down, until: { id: row.sports }, max: 15 }presses until it has, failing as soon as a press did not move the focus (focus stuck on row.news after 4 presses: a focus trap or the end of a row).assertFocusedanduntilwork on every platform that reports the focus. A TV has no touch:tap,doubleTap,longPress,scroll,scrollUntilVisible,swipeanddragfail with a message that points topressKey, andtypeonly types into a field that already has the focus. With--heala model proposes afocusinstead of a tap on a TV. The iOS agent, the iOS system runner and the sample app are built for the tvOS simulator too: new release assetsgekko-tvos-agent.zipandgekko-tvos-runner.zip, installed byscripts/install.shnext to the iOS ones, withios.tvosAgentFramework,ios.tvosRunnerDir,GEKKO_TVOS_AGENTandGEKKO_TVOS_RUNNER_DIR(ios.agentFramework: installedserves both). No change of the protocol: the buttons are names ofpressKey. The sample apps get a TV screen,scripts/e2e-android-tv.shandscripts/e2e-tvos.shrun the TV tests - Touches at a point and a drag, on Android, iOS and the web (#34):
longPress: { point: "25%,75%" }holds a spot of the screen (or, with anidor atext, a spot of that element:50%,50%is its center) for a map, a chart or a canvas that has nothing to select inside, and the newdragstep ({ drag: { start: "50%,80%", end: "50%,30%" } }, orfrom: <selector>for the start) moves the content under the start to the end and lets go without momentum, so nothing keeps scrolling: scroll by an exact distance, move a slider, reorder a list. The finger goes the touch slop beyond the end and rests there, so the content ends where the finger does: exact to the pixel on Android, through the agent and the runner, and to the point on iOS, through the agent and the system runner (the runner drags at XCUITest's slow speed: every other speed that was tried flung the content on by up to 490 points after a drag of more than 100 points). The protocol gets the commandslongPressAtanddrag(no change of the protocol version: a server that does not know them answersunsupported, and a client reads a version from 1.4.0 on as "has them") system: trueonswipeanddragmakes a real touch of the system runner instead of the in-app agent's, also on top of system UI (#34)scripts/e2e-android.shfails when the system runner is slow: a sample test forces it to hold three long presses of 900 ms and to swipe and drag, and the script checks its time (#31). The end-to-end gesture tests only ever reached the agent before, which is how the slow runner went unnoticed- The sample apps show how far their list is scrolled (
sample.list.offset, "Scroll: 240"), andscripts/e2e-android.shandscripts/e2e-ios.shcheck withscripts/check-touches.shwhat the touch tests log (#34): a drag of 10 percent of the screen followed by one of 20 percent moves the list 3 times as far in all (a finger that loses the touch slop does not), and a fast swipe flings it at least 1.5 times as far as a slow one of the same length, each through the agent and through the system runner - Typing into the field that has the focus, on Android, iOS and the web (#32): the new step
typeFocused: { value: "Ada" }(alsogekko type-focused "Ada") types at the cursor of the field a tap put the focus into, the way a keyboard does, so it adds to the text wheretypefinds a field and replaces its text. It waits for a field that takes text to get the focus (the step timeout), and fails when none does or when the field does not change;system: truetypes through the system runner. The protocol gets the commandtypeFocused, the node fieldfocused(true on the element that has the input focus, left out otherwise;gekko treeprints it; the iOS system runner leaves it out, because asking for the focus takes 0.2 to 0.5 s) and the listcommandsin the answer tohello, which names the commands a server serves (a server older than 1.4.0 leaves it out, which a client reads as the set of 1.3.0). No change of the protocol version: a server that does not know the command answersunsupported, and an older client ignores the new fields. The sample apps get a password field (sample.password) and a readout of how long what was typed into it is (sample.password.length), since its text is never readable - Pressing keys through the agents and the runners, on Android, iOS and the web (#33): the
pressKeystep takestimesandsystem(pressKey: { key: backspace, times: 2 }; the plainpressKey: enterworks as before), also asgekko press-key backspace --times 2.enter,backspace(erases to the left) andtabgo to the field that has the input focus (the step waits for one and fails when none gets it),backandhometo the app or the system, and the iOS simulators getenter,backspace,tabandhome(backdoes not exist there and fails with the server's message). The in-app agent presses what it can inside its own windows and the system runner presses everything else, so the CLI no longer sends keys overadb shell input keyevent(it still closes the keyboard that way). With the keyboard up, the firstbackon Android closes it, as on a phone; on Android 13 and newer apps take back through callbacks that a key event does not reach, so the system runner presses it there. The protocol gets the commandpressKey(key,times,timeoutMs): no change of the protocol version, a server that does not know it answersunsupported, and a client finds out fromcommandsinhello. The key to erase to the left is calledbackspace, as it is on the web, wheredeletestays the forward delete; on Android and iOSdeleteis not a key. The sample apps greet when return is pressed in the name field - Windows x64: the CLI runs on Windows 10 and newer for Android (
adb), the web (Playwright) and--heal(claude,opencodeandapithroughcurl.exe); release assetgekko-windows-x64.exe. State lives in%USERPROFILE%\.gekko; the token, the mock files and the private temp folders get an ACL that names only the current user. iOS stays macOS only scripts/install.ps1installs the Windows binary and the Android runner to~\.gekko\bin(added to the userPATH) and removes them again with-Uninstall;scripts/install.shhands over to it in Git Bash- The CLI starts every program without a shell and without
perl: the time limit, the standard input and the working directory are part of the call. Heal prompts reachclaudeandopencodeon their standard input, and the web bridge is started detached by the CLI itself gradlew.bat,.gitattributes(LF everywhere) and a Windows job in CI that tests the Windows binary and, after a merge, runs the web sample tests
Security
- The CLI and the servers it talks to authenticate each other (protocol 2). Until now the servers checked the CLI (the iOS servers and the web bridge with a token that the CLI sent in clear text, Android by the uid of the caller) but the CLI believed any answer, so a program that listened on the port or the socket first (an app on the device, another process or user of the machine) could fail tests, return a fake tree or collect the token. Now every request and every answer is signed with HMAC-SHA256 over a nonce, the endpoint, the session of the server and the body, the key never goes over the connection, and an answer that is not signed for its request stops the run with an error that names the port. Android servers get their own key, derived from the token: the agent reads it from the private directory of the app (written with
run-as) and the runner gets it as an argument ofam instrument - Text from the app under test (ids, texts, error messages, the console of a page) can no longer carry escape sequences into your terminal: the CLI turns every control character into a visible escape (
\u001b) before it prints it or writestree.txt,console.txt,failure.json, the heal report or the JUnit files, socat tree.txtafter a failed run is safe - The Gradle plugin warns about a listed variant that is not debuggable: the agent only gets its key through
run-as
Changed
- Breaking: the wire protocol is version 2. Update the CLI, the gekko Gradle plugin (or the agent dependency) and the iOS agent together; the Android and iOS system runners and the web bridge are replaced by the CLI itself, a bridge that is still running from an older gekko is ended and restarted. A CLI and a server of different protocols refuse each other with an error that says what to update
- Android: the agent only answers in a debuggable build (it gets its key through
run-as);gekko launchandgekko runfail w...
1.3.0
Immutable
release. Only release title and notes can be modified.
New
- Panes: the screens of the app as page objects. A pane is a YAML file in
panes/(panesDirrenames the folder; its path is its name,panes/checkout/payment.yamlischeckout/payment) with namedelements(one selector, or one per platform with{ android, ios, web }), anidentity(the elements that prove the screen is shown) andactions(named steps withparams). Steps refer to elements withtap: auth/login.submitor{ element: auth/login.submit, index: 2 }(the keys of the step are added to the element's, the step wins on a clash), check a screen withassertPane: auth/login,until: { assertPane: ... }andif: { pane: ... }, and call actions withuse: auth/login.signInandwith:(also inuses:and in thesetupandteardownof a group). An action waits for the identity of its pane before its first step. See "Panes" in the format reference - Panes in the diagnostics:
gekko checknames unknown panes, elements and actions with a hint and warns about elements, actions and panes that nothing uses; a failed step names the element and what it stands for and thecurrent pane;gekko treemarks the elements of the panes (<- auth/login.email) and prints the current pane; the heal report names the element and the pane file to fix - The
gekko-authorskill readspanes/, writes steps with elements and pane actions and puts new elements into the pane instead of the test; the test-repo template'sAGENTS.mddescribes the folder.docs/how-it-works.mdhas a section and an illustration for panes - Network mocks: a
mockstep answers the requests of the app that match a URL (a glob with*, optionally amethodand abodyContainsfor GraphQL) with the content of a file belowmocks/(mocksDirrenames the folder), with an optionalstatus,headersanddelayMs;clearMockstakes every mock away. A test always undoes every mock when it ends, whether it passed or failed. Mock steps at the very start of a test (also in flows) are set before the app starts, so the requests the app makes while it starts are answered too. Android (OkHttp andHttpURLConnectionof a debuggable build with the Gradle plugin, emulators and devices), iOS simulators (URLSession) and the web (every request of the page) are covered; a request that matches no mock goes to the real backend. The log shows every answered request and a mock that no request used is a warning (also in the JUnit file). See "Network mocks" in the format reference ${now(+10m)},${now(-1d, 'HH:mm')}and${now(+10m, epochMillis)}give a point in time relative to the clock of the device, for mock files whose times have to stay in the futuregekko { networkMocks.set(false) }in the Gradle plugin switches off the OkHttp andHttpURLConnectionhooks that the mocks need (on by default in the variants that get the agent of the same release; withversionoragentset it is off unless you switch it on, because the hooks call classes that only the agent of the same release has)gekko checkreports a mock file that is missing, a placeholder in it that is written wrong and a file that is no UTF-8 text (mock files are text only)- The sample apps make a request to a host that does not exist, and
network-mocktests show the three platforms answering it from files
Changed
- Android: the agent no longer reports rows of a lazy list that scrolled out of view as on screen. Compose keeps them in its tree without placing them, so their old positions made
assertNotVisibleon a scrolled-away row fail (seen on Android 15 and 16 emulators)
SHA-256
Verify a download with gh attestation verify <file> --repo jakala-germany/gekko; the hashes are also in the SHA256SUMS asset.
d9fac7dffc6c94e2b7b9d980cbdd9097585af3dcf13fd364515f454f265cb0f9 gekko-ios-agent.zip
ae7f081df9f7e6b8b9cc9dd0a4fdb5b749d57f784aa1b0ca60cfa93015a142c3 gekko-ios-runner.zip
3dc382e02a46399d8ac5ce89cd8e35e79e76ca35ccce5f503db3694c5a9eb4fd gekko-linux-x64
dcf6ee63cb4eaf0d192b493a5e9e4c2ff48a9777bff34b063ff869c35e65284f gekko-macos-arm64
793b767e1df5c6c4bb386bd50181d61683b84d1e01ab070ff956da33b3a19927 gekko-system-runner.apk
1.2.0
Immutable
release. Only release title and notes can be modified.
New
- Web: gekko tests web apps in Chromium, Firefox and WebKit through Playwright, with the same YAML tests. A web app needs nothing built in:
app.webingekko.yamlnames a URL (or an HTML file or folder of the project, served on127.0.0.1),gekko install --platform web -s <browser>installs Playwright and the browser (Node.js 18 or newer), andgekko run --platform web -s firefoxor--devices chromium,firefox,webkitruns the tests. A web device is a named browser session that outlives a CLI call, sogekko launch,gekko treeandgekko tapwork step by step. Elements are named bydata-testid(orflt-semantics-identifier, seeweb.idAttributes), text and accessible labels - Web: browser dialogs (
alert,confirm,prompt,beforeunload) show up as the topmost window and are answered withtap: { text: OK, system: true }; taps, typing and scrolling bring an element of the page into view;setDarkMode,setAirplaneMode(offline),setOrientation,setLocation,setPermissions,device.language,device.timeFormat,back,pressKey,openLinkand video (--record, asvideo.webm) work; failed tests also leaveconsole.txt platform:on a step or an action takes a list:platform: [android, web]. A per-platform id has to name every platform that has anapp:entry ingekko.yaml(Android and iOS as before)scripts/install.sh --web[=chromium,firefox,webkit]also installs Playwright and the browsers;gekko deviceslists running web sessionsscripts/e2e-web.shand a web end-to-end job in CI run the sample tests in all three browsers;sample-web/is the sample app (the same ids as the Android and iOS samples), with web-only tests for dialogs, navigation, dark mode and page scrolling- Web:
web.session: shared(orGEKKO_WEB_SESSION=shared) keeps one browser context for all tests of a run, in memory only: log in once instead of in every test, or log in by hand in a visible browser (GEKKO_WEB_HEADED=1 gekko launch) and run the suite in that session - Groups: a folder of tests with a
group.yaml(setup, optionalteardownandname) shares one start state, typically a login. The setup flows run once, the tests follow in one session without clearing the app data (a browser keeps its context), and a failed setup skips the tests (SKIP, JUnitskipped) instead of failing each.platform:in thegroup.yaml(webor a list) limits a group to those platforms, so its tests need noplatform:on every step. A group is never split over devices or shards. The setup and teardown are reported as tests of their own app.webmay name a declared variable (https://app-${env.STAGE}.example.com/), so one project serves every environment- The mock location test runs on the web too (tag
locationinstead ofandroid-only)
Changed
Device.freshStarttakeskeepStateandDevice.endTest(config, keepSession)is new (for groups; the defaults keep the old behavior). A test result can beskipped; the JUnit file has askippedcount- The element lookup and waiting code of the Android agent (
com.jakala.gekko.device:ElementLookup,Waiting,Scrolling,NodeFacts) moved fromgekko-transport-jvmtogekko-protocol, which the web agent in the CLI shares; the package stays, so nothing changes for users ofgekko-transport-jvm - The UI node has an optional
clip(where its ancestors cut it off) and the protocol awheelcommand; only the web agent uses them, so the protocol number stays 1 - The CLI reference marks the diagnostic and internal environment variables as not covered by the compatibility promise and lists
GEKKO_MOCK_LOCATION,GEKKO_TARGET_BUNDLE_IDandGEKKO_TAP_VERIFY
SHA-256
Verify a download with gh attestation verify <file> --repo jakala-germany/gekko; the hashes are also in the SHA256SUMS asset.
3b24a0ca02d03ae117c807f80eea487633b106e1a98cf16c7e6b0893bda2b3fd gekko-ios-agent.zip
ac3059e0e51799b91ed329fa63f30645253c0234cdfe92d4ecd62db25da172f7 gekko-ios-runner.zip
456cbba9a37e7afea6314b7f165abd06749c0d3260b85396ca8afaa616d18a48 gekko-linux-x64
fce465354fec820b35fdcf807085f97df0ec9eba3a08c4d66390ee377825f2f6 gekko-macos-arm64
c4eabd2036a3291cd55396ce94696dac7b204e441d207b2ef41f7dfd44953664 gekko-system-runner.apk
1.1.0
Immutable
release. Only release title and notes can be modified.
New
setLocationworks on physical Android devices: the system runner feeds Android's mock location providers (gps,network), gekko switches it on as the mock location app withappopsand ends the mock location when the test endsgekko llm-checkasks the model of--healone short question and prints the answer, soGEKKO_LLM_*(or the local CLI) can be tried without a deviceGEKKO_LLM_CA_CERTnames the PEM file of a private CA for--heal api
Fixed
- The Android agent and the system runner answered no request on a device below API 33: the server read requests with
ByteArrayOutputStream.toString(Charset), which Android only has from API 33, and the error was swallowed, so every connection closed without a reply ("In-process agent did not respond") setDarkMode,setAirplaneModeanddevice.languagefail with the API they need (29, 30, 33) on an older Android device instead of doing nothing
Changed
- The Android agent has minSdk 21 (was 26), so an app with a lower minSdk no longer needs
tools:overrideLibrary="com.jakala.gekko.agent"; remove it if an earlier build asked for it. The system runner needs API 24 (was 26), andgekkostops with a clear error on an emulator or device older than that --heal apiworks overhttps://in the native binary: the request goes throughcurl, because Ktor CIO has no TLS on Kotlin/Native (the heal failed with "TLS sessions are not supported on Native platform").curlmust be on thePATH
SHA-256
Verify a download with gh attestation verify <file> --repo jakala-germany/gekko; the hashes are also in the SHA256SUMS asset.
9e908c69120f2d354ee694fc53088cb7dd3593e13f2d30e8eea0163e2666dd50 gekko-ios-agent.zip
337563ede78d5e2852530880449e49ffc4ccb617e460eb2488867abac0f9095c gekko-ios-runner.zip
14466fac6780b9a0cd7501318ac1046f2a249a86aee23ec364366953396b6704 gekko-linux-x64
855fdc5b9a341bb51cac3fa38455b0835ee2c07681f4d16e03a5209a7a16b4bb gekko-macos-arm64
c054c0c7b7d90284459f735ac48e4d37d73193554e4ab17eed48582477ba6ce5 gekko-system-runner.apk
1.0.0
Immutable
release. Only release title and notes can be modified.
First release. UI tests written once in YAML run on Android and on iOS simulators.
Tests and flows
- Steps with
say(intent),do(exactly one action),untilandattempts; reusable flows with parameters; test-level
uses:;platform:per step;if,optional,repeat. - Actions:
tap,doubleTap,longPress,type,eraseText,scroll,scrollUntilVisible,swipe,
assertVisible,assertNotVisible,waitForAnimationToEnd,wait,back,pressKey,openLink,launchApp,
stopApp,clearState,takeScreenshot,setDarkMode,setAirplaneMode,setOrientation,setLocation,
setPermissions,copyText,hideKeyboard,launchPackage,stopPackage. - Selectors by
id,text,textContains,textMatches,action,within,index,enabled,checked,
selected. Scrolling uses reading directions (down,up,start,end,left,right). - Variables:
${var.x}fromcopyText,${date(...)},${random.email},${random.number(n)},${random.uuid}and
${env.NAME}for the variablesgekko.yamldeclares inenv:(values are masked in all output).
CLI
gekko run(tags,--exclude-tags, shards, several devices,--every-device,--junit,--record),gekko check,
gekko devices,install,uninstall,launch,tree,tap,type,scroll,assert,screenshot,
gekko --version.- Exit codes: 0 passed, 1 a test failed, 2 usage, configuration or version problem, 3 device, agent or runner problem.
--heal claude|opencode|apifills in for missing ids and reports what it used (gekko-heal-report.md,
--junit-healed); assertions are only healed when the id is nowhere on the screen.
Platforms
- Android: in-app agent through the Gradle plugin
io.github.jakala-germany.gekko, system runner (UiAutomator). - iOS simulators: agent injected at launch, system runner (XCUITest).
- CLI for macOS arm64 and Linux x64; install with
scripts/install.shor, in CI, the setup action
jakala-germany/setup-gekko-cli-action.
SHA-256
Verify a download with gh attestation verify <file> --repo jakala-germany/gekko; the hashes are also in the SHA256SUMS asset.
c152c93ed83ff485291eb88aef64261774ccd7da84f6d18afc4d09d4a69513a0 gekko-ios-agent.zip
e45ab5f68ab35330dc69385fe3f817b3ad72283320cddd7f952adcec8c2f8eef gekko-ios-runner.zip
999fa8612aedd65a4f58c2e810e42d4a38b2c91f6b906d717481c1a552d91e08 gekko-linux-x64
978be2eb28b093a605de25e464af4fe895069268f9200258c5ebf4bc0f465f26 gekko-macos-arm64
2d2da094cbd0e91b869e9c842b2e6c05dfccc0fbbaf41d3fddaab2b62494b519 gekko-system-runner.apk