feat: kitten-lynx, a puppeteer like, android emulator based, testing infrastructure by PupilTong · Pull Request #2272 · lynx-family/lynx-stack

PupilTong · 2026-02-26T11:29:44Z

Summary by CodeRabbit

New Features
- Kitten-Lynx testing framework: connect to app, create pages, navigate, query elements, read styles, perform taps, and consolidated public exports.
CI
- Added Android emulator-based integration job to run end-to-end tests.
Tests
- Added end-to-end test validating navigation, content reading, element querying, style inspection, and interactions.
Bug Fixes
- Improved app launch fallback for more reliable startup.
Documentation
- Added comprehensive guides, examples, and troubleshooting notes.
Chores
- Added release changeset and package metadata for initial publish.

Checklist

Tests updated (or not required).
Documentation updated (or not required).
Changeset added, and when a BREAKING CHANGE occurs, it needs to be clearly marked (or not required).

changeset-bot · 2026-02-26T11:29:49Z

🦋 Changeset detected

Latest commit: 1f6a24b

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@lynx-js/kitten-lynx-test-infra	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

coderabbitai · 2026-02-26T11:29:55Z

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

@coderabbitai resume to resume automatic reviews.
@coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

▶️ Resume reviews
🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds a new Kitten-Lynx testing library (ADB + CDP) with source, tests, docs, configs, and exports; introduces a CI emulator job and changeset; and updates Android transport fallback in devtool connector to use dumpsys/am start when monkey output lacks expected markers.

Changes

Cohort / File(s)	Summary
Framework Core `packages/testing-library/kitten-lynx/src/Lynx.ts`, `packages/testing-library/kitten-lynx/src/KittenLynxView.ts`, `packages/testing-library/kitten-lynx/src/ElementNode.ts`, `packages/testing-library/kitten-lynx/src/CDPChannel.ts`, `packages/testing-library/kitten-lynx/src/index.ts`	Added public modules: Lynx connect/newPage/close API, KittenLynxView page model (navigation, attach, content), ElementNode interactions (tap, attributes, styles), typed per-session CDPChannel, and barrel exports.
Tests `packages/testing-library/kitten-lynx/tests/lynx.spec.ts`	New end-to-end Vitest spec exercising connect, navigation, DOM inspection, computed styles, and tap interaction.
Docs `packages/testing-library/kitten-lynx/README.md`, `packages/testing-library/kitten-lynx/AGENTS.md`	Added usage and architecture docs, prerequisites, gotchas, extension guidance, and developer notes.
Project Configuration `packages/testing-library/kitten-lynx/package.json`, `packages/testing-library/kitten-lynx/tsconfig.json`, `packages/testing-library/kitten-lynx/vitest.config.ts`	New package manifest with exports and scripts, TypeScript config with path aliases and declaration output, and Vitest config (node env, timeouts).
CI & Release `.github/workflows/test.yml`, `.changeset/sharp-dragons-search.md`	Added `kitten-lynx-android-emulator` CI job to run emulator-based tests and a changeset declaring a patch release for `@lynx-js/kitten-lynx-test-infra`.
Transport Fix `packages/mcp-servers/devtool-connector/src/transport/android.ts`	Modified openApp() to treat missing "Events injected:" as failure and added a dumpsys + `am start` fallback before throwing a consolidated error.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Suggested reviewers

colinaaa
upupming
hzy

Poem

🐰 I hopped through code and CI light,
pages, channels, docs in sight,
a tap, a dump, an emulator song,
tests and changesets marching along,
tiny paws push builds along 🥕

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main addition: a new testing infrastructure called kitten-lynx with Puppeteer-like API and Android emulator support.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests

📝 Coding Plan

Generate coding plan for human review comments

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

codecov · 2026-02-26T11:34:13Z

Codecov Report

❌ Patch coverage is 69.80000% with 151 lines in your changes missing coverage. Please review.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
.../testing-library/kitten-lynx/src/KittenLynxView.ts	73.33%	60 Missing ⚠️
...servers/devtool-connector/src/transport/android.ts	0.00%	38 Missing ⚠️
packages/testing-library/kitten-lynx/src/Lynx.ts	75.42%	29 Missing ⚠️
...ges/testing-library/kitten-lynx/src/ElementNode.ts	77.50%	18 Missing ⚠️
...ackages/mcp-servers/devtool-connector/src/index.ts	0.00%	5 Missing ⚠️
packages/testing-library/kitten-lynx/src/index.ts	0.00%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

.github/workflows/workflow-test.yml

codspeed-hq · 2026-02-27T04:36:08Z

Merging this PR will not alter performance

✅ 72 untouched benchmarks
⏩ 3 skipped benchmarks¹

_{Comparing PupilTong:p/hw/based-on-emulator-testing (1f6a24b) with main (6d8e125)}

3 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

relativeci · 2026-02-27T04:39:40Z

Web Explorer

#8207 Bundle Size — 385.21KiB (0%).

1f6a24b(current) vs 6d8e125 main#8200(baseline)

Bundle metrics no changes

	Current #8207	Baseline #8200
Initial JS	`155.59KiB`	`155.59KiB`
Initial CSS	`35.1KiB`	`35.1KiB`
Cache Invalidation	`0%`	`0%`
Chunks	`8`	`8`
Assets	`8`	`8`
Modules	`239`	`239`
Duplicate Modules	`16`	`16`
Duplicate Code	`2.97%`	`2.97%`
Packages	`4`	`4`
Duplicate Packages	`0`	`0`

Bundle size by type no changes

	Current #8207	Baseline #8200
JS	`254.26KiB`	`254.26KiB`
Other	`95.85KiB`	`95.85KiB`
CSS	`35.1KiB`	`35.1KiB`

Bundle analysis report Branch PupilTong:p/hw/based-on-emulator... Project dashboard

^{Generated by RelativeCI Documentation Report issue}

.github/workflows/workflow-test.yml

…t workflow.

…r` for Android SDK setup in CI.

…n the CI workflow.

…ttenLynx API usage and internal mechanics for agents.

…lusions and dependencies.

…st-infra` across all relevant files.

…ch event emulation with a 50ms delay.

…er for bundles, refining session matching logic, and adding resource cleanup.

…, update TypeScript module resolution to `Bundler`, and remove immediate `DOM.getDocument` call on session attach.

This PR was opened by the [Changesets release](https://github.com/changesets/action) GitHub action. When you're ready to do a release, you can merge this and the packages will be published to npm automatically. If you're not ready to do a release yet, that's fine, whenever you add more changesets to main, this PR will be updated. # Releases ## @lynx-js/react@0.117.0 ### Minor Changes - feat: export `GlobalPropsProvider`, `GlobalPropsConsumer`, `useGlobalProps` and `useGlobalPropsChanged` for `__globalProps` ([#2346](#2346)) - `GlobalPropsProvider`: A Provider component that accepts `children`. It is used to provide the `lynx.__globalProps` context. - `GlobalPropsConsumer`: A Consumer component that accepts a function as a child. It is used to consume the `lynx.__globalProps` context. - `useGlobalProps`: A hook that returns the `lynx.__globalProps` object. It triggers a re-render when `lynx.__globalProps` changes. - `useGlobalPropsChanged`: A hook that accepts a callback function. The callback is invoked when `lynx.__globalProps` changes. Note: When `globalPropsMode` is not set to `'event'` (default is `'reactive'`), these APIs will be ineffective (pass-through) and will log a warning in development mode, as updates are triggered automatically by full re-render. - **BREAKING CHANGE**: ([#2319](#2319)) Change preact package from `@hongzhiyuan/preact` to `@lynx-js/internal-preact`. Upgrade preact from [f7693b72](preactjs/preact@f7693b7) to [55254ef7](preactjs/preact@55254ef), see diffs at [f7693b72...55254ef7](https://github.com/preactjs/preact/compare/f7693b72ecb4a40c66e6e47f54e2d4edc374c9f0...preactjs:preact:55254ef7021e563cc1a86fb816058964a1b6a29a?expand=1). - feat: add `globalPropsMode` option to `PluginReactLynxOptions` ([#2346](#2346)) - When configured to `"event"`, `updateGlobalProps` will only trigger a global event and skip the `runWithForce` flow. - Defaults to `"reactive"`, which means `updateGlobalProps` will trigger re-render automatically. ### Patch Changes - Add `__BACKGROUND__` guard on `onBackgroundSnapshotInstanceUpdateId` event to prevent bundling to main-thread on dev environment. ([#2332](#2332)) - refactor: extract static string in template literal ([#2334](#2334)) - fix: avoid crash when spread undefined ref ([#2333](#2333)) - Avoid registering lifecycle refs for main-thread functions (MTF) that have not received an `execId` during `renderPage()` first-screen binding. ([#2320](#2320)) ## @lynx-js/react-umd@0.117.0 ### Minor Changes - Add standalone UMD build of the ReactLynx runtime. ([#2331](#2331)) ## @lynx-js/react-rsbuild-plugin@0.13.0 ### Minor Changes - **BREAKING CHANGE**: ([#2319](#2319)) Change preact package from `@hongzhiyuan/preact` to `@lynx-js/internal-preact`. Upgrade preact from [f7693b72](preactjs/preact@f7693b7) to [55254ef7](preactjs/preact@55254ef), see diffs at [f7693b72...55254ef7](https://github.com/preactjs/preact/compare/f7693b72ecb4a40c66e6e47f54e2d4edc374c9f0...preactjs:preact:55254ef7021e563cc1a86fb816058964a1b6a29a?expand=1). - feat: add `globalPropsMode` option to `PluginReactLynxOptions` ([#2346](#2346)) - When configured to `"event"`, `updateGlobalProps` will only trigger a global event and skip the `runWithForce` flow. - Defaults to `"reactive"`, which means `updateGlobalProps` will trigger re-render automatically. ### Patch Changes - Updated dependencies \[[`f1129ea`](f1129ea), [`27f1cff`](27f1cff), [`ed566f0`](ed566f0), [`402ec2b`](402ec2b)]: - @lynx-js/react-webpack-plugin@0.8.0 - @lynx-js/react-refresh-webpack-plugin@0.3.5 - @lynx-js/react-alias-rsbuild-plugin@0.13.0 - @lynx-js/use-sync-external-store@1.5.0 - @lynx-js/template-webpack-plugin@0.10.6 - @lynx-js/css-extract-webpack-plugin@0.7.0 ## @lynx-js/react-webpack-plugin@0.8.0 ### Minor Changes - feat: add `globalPropsMode` option to `PluginReactLynxOptions` ([#2346](#2346)) - When configured to `"event"`, `updateGlobalProps` will only trigger a global event and skip the `runWithForce` flow. - Defaults to `"reactive"`, which means `updateGlobalProps` will trigger re-render automatically. ### Patch Changes - Fix sourcemap misalignment when wrapping lazy bundle main-thread chunks. ([#2361](#2361)) The lazy bundle IIFE wrapper is now injected in `processAssets` at `PROCESS_ASSETS_STAGE_OPTIMIZE_SIZE + 1` by walking chunk groups instead of patching assets in `beforeEncode`. - With `experimental_isLazyBundle: true`, the wrapper is applied to lazy-bundle chunk groups. - Without lazy bundle mode, the wrapper is applied to async main-thread chunk groups generated by dynamic import. Injecting the wrapper in this stage keeps the emitted JS stable after optimization while still running before `DEV_TOOLING` sourcemap finalization, so the generated `.js` and `.js.map` stay aligned. - Set `__DEV__` and `__PROFILE__` to `true` on `NODE_ENV === 'development'`. ([#2324](#2324)) ## @lynx-js/rspeedy@0.13.6 ### Patch Changes - Rename Web Preview label to fix URL alignment ([#2355](#2355)) - Updated dependencies \[[`799fda8`](799fda8)]: - @lynx-js/cache-events-webpack-plugin@0.0.3 - @lynx-js/web-rsbuild-server-middleware@0.19.9 ## @lynx-js/lynx-bundle-rslib-config@0.2.3 ### Patch Changes - Fix snapshot not found error when dev with external bundle ([#2316](#2316)) ## @lynx-js/external-bundle-rsbuild-plugin@0.0.4 ### Patch Changes - Updated dependencies \[[`ed566f0`](ed566f0)]: - @lynx-js/externals-loading-webpack-plugin@0.0.5 ## @lynx-js/kitten-lynx-test-infra@0.1.1 ### Patch Changes - feat: support page.screenshot() ([#2364](#2364)) - feat: initial commit ([#2272](#2272)) ## @lynx-js/testing-environment@0.1.12 ### Patch Changes - Implement `__ElementAnimate` PAPI for web platform animation lifecycle ([#2329](#2329)) ## @lynx-js/web-constants@0.19.9 ### Patch Changes - Implement `__ElementAnimate` PAPI for web platform animation lifecycle ([#2329](#2329)) - Updated dependencies \[]: - @lynx-js/web-worker-rpc@0.19.9 ## @lynx-js/web-core@0.19.9 ### Patch Changes - Updated dependencies \[[`2efecc2`](2efecc2)]: - @lynx-js/web-constants@0.19.9 - @lynx-js/web-mainthread-apis@0.19.9 - @lynx-js/web-worker-runtime@0.19.9 - @lynx-js/web-worker-rpc@0.19.9 ## @lynx-js/web-core-wasm@0.0.6 ### Patch Changes - reexports essential utils & types in @lynx-js/web-elements from @lynx-js/web-core-wasm/client ([#2321](#2321)) - Updated dependencies \[]: - @lynx-js/web-worker-rpc@0.19.9 ## @lynx-js/web-mainthread-apis@0.19.9 ### Patch Changes - Updated dependencies \[[`2efecc2`](2efecc2)]: - @lynx-js/web-constants@0.19.9 ## @lynx-js/web-worker-runtime@0.19.9 ### Patch Changes - Updated dependencies \[[`2efecc2`](2efecc2)]: - @lynx-js/web-constants@0.19.9 - @lynx-js/web-mainthread-apis@0.19.9 - @lynx-js/web-worker-rpc@0.19.9 ## @lynx-js/cache-events-webpack-plugin@0.0.3 ### Patch Changes - Cache `globalThis.loadDynamicComponent` in the cache events runtime and add tests covering tt methods, performance events, and globalThis replay behavior. ([#2343](#2343)) ## @lynx-js/externals-loading-webpack-plugin@0.0.5 ### Patch Changes - Fix snapshot not found error when dev with external bundle ([#2316](#2316)) ## @lynx-js/react-refresh-webpack-plugin@0.3.5 ### Patch Changes - Fix snapshot not found error when dev with external bundle ([#2316](#2316)) ## @lynx-js/template-webpack-plugin@0.10.6 ### Patch Changes - Updated dependencies \[[`d034dae`](d034dae)]: - @lynx-js/web-core-wasm@0.0.6 ## create-rspeedy@0.13.6 ## @lynx-js/react-alias-rsbuild-plugin@0.13.0 ## upgrade-rspeedy@0.13.6 ## @lynx-js/web-core-server@0.19.9 ## @lynx-js/web-rsbuild-server-middleware@0.19.9 ## @lynx-js/web-worker-rpc@0.19.9 Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

PupilTong self-assigned this Feb 26, 2026

github-advanced-security bot found potential problems Feb 26, 2026

View reviewed changes

.github/workflows/workflow-test.yml Fixed Show fixed Hide fixed

github-advanced-security bot found potential problems Feb 27, 2026

View reviewed changes

.github/workflows/workflow-test.yml Fixed Show fixed Hide fixed

PupilTong force-pushed the p/hw/based-on-emulator-testing branch from f9adc32 to 49d9236 Compare February 27, 2026 08:22

github-advanced-security bot found potential problems Feb 27, 2026

View reviewed changes

.github/workflows/workflow-test.yml Fixed Show fixed Hide fixed

PupilTong force-pushed the p/hw/based-on-emulator-testing branch from 49d9236 to 5ad9602 Compare February 27, 2026 08:39

github-advanced-security bot found potential problems Feb 27, 2026

View reviewed changes

.github/workflows/workflow-test.yml Fixed Show fixed Hide fixed

PupilTong force-pushed the p/hw/based-on-emulator-testing branch 4 times, most recently from c487be1 to c45cd6b Compare March 6, 2026 10:22

github-advanced-security bot found potential problems Mar 9, 2026

View reviewed changes

.github/workflows/workflow-test.yml Fixed Show fixed Hide fixed

.github/workflows/workflow-test.yml Fixed Show fixed Hide fixed

.github/workflows/workflow-test.yml Fixed Show fixed Hide fixed

PupilTong force-pushed the p/hw/based-on-emulator-testing branch 12 times, most recently from 585c18c to cb21ae0 Compare March 12, 2026 09:04

PupilTong marked this pull request as ready for review March 12, 2026 09:50

PupilTong added 24 commits March 18, 2026 11:51

feat: Install Waydroid and initialize it with a vanilla image.

c542281

chore: Add kmod package to Waydroid installation in the test workflow.

6a5c0d5

ci: Install Waydroid kernel modules and their dependencies in the tes…

d17cc1b

…t workflow.

+ fix

5030f5c

fix: Explicitly set ANDROID_HOME and use --sdk_root with `sdkmanage…

5bf624f

…r` for Android SDK setup in CI.

+ fix

634592f

+ remove install stage

2ea97fb

+ fix url

8958529

+ waiting time

69e6d66

+ fix

fdce55f

ci: Start and verify Lynx Explorer application before running tests i…

e1ca7fe

…n the CI workflow.

+ log

b3290b9

+ fix

30c8fda

+ essential infos

57aca0c

docs: Correct typo "chould" to "could" in AGENTS.md.

51a1019

+ fix dedupe

cea23be

docs: Add comprehensive JSDoc comments and a new README to clarify Ki…

53fadb5

…ttenLynx API usage and internal mechanics for agents.

Remove container-image parameter from workflows and adjust test exc…

da748a5

…lusions and dependencies.

refactor: rename @lynx-test/kitten-lynx to `@lynx-js/kitten-lynx-te…

f264485

…st-infra` across all relevant files.

refactor: Migrate ADB interactions to @yume-chan/adb and adjust tou…

b92aa16

…ch event emulation with a 50ms delay.

chore: update pnpm lockfile

32ebdfe

+ report coverage

1d38cc8

feat: Improve kitten-lynx test stability by implementing local serv…

c3b1fd7

…er for bundles, refining session matching logic, and adding resource cleanup.

feat: Implement cmd package resolve-activity for Android app launch…

1f6a24b

…, update TypeScript module resolution to `Bundler`, and remove immediate `DOM.getDocument` call on session attach.

PupilTong force-pushed the p/hw/based-on-emulator-testing branch from c854154 to 1f6a24b Compare March 18, 2026 03:51

PupilTong merged commit 74603cb into lynx-family:main Mar 18, 2026
81 of 83 checks passed

github-actions bot mentioned this pull request Mar 18, 2026

chore: Release 2026-03-24 02:07:53 #2323

Merged

This was referenced Mar 19, 2026

feat: Add a React example application to the kitten-lynx test fixture… #2356

Merged

feat: add more apis for kitten-lynx #2364

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: kitten-lynx, a puppeteer like, android emulator based, testing infrastructure#2272

feat: kitten-lynx, a puppeteer like, android emulator based, testing infrastructure#2272
PupilTong merged 31 commits intolynx-family:mainfrom
PupilTong:p/hw/based-on-emulator-testing

PupilTong commented Feb 26, 2026 •

edited by coderabbitai bot

Loading

Uh oh!

changeset-bot bot commented Feb 26, 2026 •

edited

Loading

Uh oh!

coderabbitai bot commented Feb 26, 2026 •

edited

Loading

Reviews paused

Walkthrough

Changes

Estimated code review effort

Suggested reviewers

Poem

Uh oh!

codecov bot commented Feb 26, 2026 •

edited

Loading

Uh oh!

Uh oh!

codspeed-hq bot commented Feb 27, 2026 •

edited

Loading

Uh oh!

relativeci bot commented Feb 27, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

PupilTong commented Feb 26, 2026 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Checklist

Uh oh!

changeset-bot bot commented Feb 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

coderabbitai bot commented Feb 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reviews paused

Walkthrough

Changes

Estimated code review effort

Suggested reviewers

Poem

Uh oh!

codecov bot commented Feb 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

codspeed-hq bot commented Feb 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merging this PR will not alter performance

Footnotes

Uh oh!

relativeci bot commented Feb 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Web Explorer

#8207 Bundle Size — 385.21KiB (0%).

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

PupilTong commented Feb 26, 2026 •

edited by coderabbitai bot

Loading

changeset-bot bot commented Feb 26, 2026 •

edited

Loading

coderabbitai bot commented Feb 26, 2026 •

edited

Loading

codecov bot commented Feb 26, 2026 •

edited

Loading

codspeed-hq bot commented Feb 27, 2026 •

edited

Loading

relativeci bot commented Feb 27, 2026 •

edited

Loading