feat: add more apis for kitten-lynx

[PupilTong]

Summary by CodeRabbit

• New Features

  • Page screenshot capture: returns an in-memory Buffer or optionally saves to disk; supports JPEG/PNG/WebP and configurable quality.

• Tests

  • Added tests for screenshot integrity, element attribute queries, computed style inspection, and interactive UI state transitions.

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]

🦋 Changeset detected

Latest commit: 4d3668c

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]

📝 Walkthrough

Walkthrough

Adds a screenshot() method to KittenLynxView (CDP stream → base64 → Buffer, optional file write), test coverage for screenshots and interactions, changeset metadata, build/config changes, and dev dependency additions.

Changes

Cohort / File(s)	Summary
Core Implementation packages/testing-library/kitten-lynx/src/KittenLynxView.ts	Adds `async screenshot(options?: { path?: string; format?: 'jpeg'
Tests packages/testing-library/kitten-lynx/tests/lynx.spec.ts	Creates shared page in beforeAll; adds attribute/style assertions, interaction/tap test, and a screenshot test that asserts a non-empty Buffer and verifies pixels using jpeg-js.
Build / Config / Metadata .changeset/olive-readers-turn.md, packages/testing-library/kitten-lynx/lynx.config.js, packages/testing-library/kitten-lynx/package.json, packages/testing-library/kitten-lynx/rslib.config.ts, packages/testing-library/kitten-lynx/tsconfig.json	Adds changeset for a patch bump; sets output.assetPrefix in Lynx config; switches build script to rslib build; adds jpeg-js and rsbuild-plugin-publint to devDependencies; adds rslib.config.ts; removes baseUrl from tsconfig.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• feat: kitten-lynx, a puppeteer like, android emulator based, testing infrastructure #2272: Introduced the KittenLynxView implementation that this PR extends with screenshot().
• feat: Add a React example application to the kitten-lynx test fixture… #2356: Modified KittenLynxView earlier (goto(), onAttachedToTarget), touching related APIs.

Suggested reviewers

• Huxpro
• colinaaa

Poem

🐇
I hopped through CDP where pixels play,
I nibbled base64 and carried away.
A buffered bloom, a snapshot near—
Saved to disk or held so dear. 📸✨

🚥 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 captures the main change: adding new APIs (screenshot method) to the kitten-lynx testing library for page screenshots.
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

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[codecov]

Codecov Report

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

Files with missing lines	Patch %	Lines
...ckages/testing-library/kitten-lynx/rslib.config.ts	0.00%	10 Missing ⚠️
.../testing-library/kitten-lynx/src/KittenLynxView.ts	89.36%	5 Missing ⚠️
...ackages/testing-library/kitten-lynx/lynx.config.js	0.00%	3 Missing ⚠️

📢 Thoughts on this report? Let us know!

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (2)

packages/testing-library/kitten-lynx/tests/lynx.spec.ts (1)

91-96: Consider using setTimeout from node:timers/promises for cleaner delays.

The test already imports setTimeout from node:timers/promises (via the module, visible in KittenLynxView.ts). Using await setTimeout(2000) would be cleaner than wrapping in a Promise constructor.

♻️ Cleaner delay syntax

+import { setTimeout } from 'node:timers/promises';
+
 // In the test:
-    await new Promise(resolve => setTimeout(resolve, 2000));
+    await setTimeout(2000);

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/testing-library/kitten-lynx/tests/lynx.spec.ts` around lines 91 -
96, Replace the Promise-wrapped delays in the test with the imported setTimeout
from node:timers/promises: instead of awaiting new Promise(resolve =>
setTimeout(resolve, 2000)), use await setTimeout(2000); update the two
occurrences in lynx.spec.ts (the delays before checking
`.Logo--react`/`.Logo--lynx` and after logoParent?.tap()) and ensure the module
import for setTimeout is present and not shadowed by any local variable.

packages/testing-library/kitten-lynx/src/KittenLynxView.ts (1)

366-370: Consider using await using for cleaner disposal.

TypeScript 5.x supports the await using syntax which automatically handles async disposal. The current manual approach works but is more verbose.

♻️ Optional refactor using await using

-    const stream = await this._connector.sendCDPStream(
+    await using stream = await this._connector.sendCDPStream(
       this._clientId,
       ReadableStream.from([
         { method: 'Lynx.getScreenshot', sessionId } as any,
       ]),
     );

     let buffer: Buffer | undefined;

-    try {
-      for await (const msg of stream) {
-        if (msg.method === 'Lynx.screenshotCaptured') {
-          const data = (msg.params as any).data;
-          if (data) {
-            buffer = Buffer.from(data, 'base64');
-            break;
-          }
+    for await (const msg of stream) {
+      if (msg.method === 'Lynx.screenshotCaptured') {
+        const data = (msg.params as any).data;
+        if (data) {
+          buffer = Buffer.from(data, 'base64');
+          break;
         }
       }
-    } finally {
-      if (typeof stream[Symbol.asyncDispose] === 'function') {
-        await stream[Symbol.asyncDispose]();
-      }
     }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/testing-library/kitten-lynx/src/KittenLynxView.ts` around lines 366
- 370, Replace the manual disposal in the try/finally that checks
stream[Symbol.asyncDispose] with TypeScript 5's await using syntax: bind the
async-disposable stream with "await using" (e.g., await using const s = stream)
before the block that consumes it, use s inside the block, and remove the
finally block that calls stream[Symbol.asyncDispose](); ensure the code that
referenced stream now uses the new bound variable (stream -> s) and that your
tsconfig/target supports the "await using" feature so compilation succeeds.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@packages/testing-library/kitten-lynx/src/KittenLynxView.ts`:
- Around line 339-352: The screenshot method can hang because sendCDPStream's
optional signal isn't used and the format/quality options aren't forwarded;
update the screenshot function to create an AbortController (or accept a
timeout), pass controller.signal to this._connector.sendCDPStream, and ensure
the controller is aborted on timeout or when the stream completes to avoid
indefinite blocking; also include the declared options.format and
options.quality in the CDP request payload sent to ReadableStream.from (the
Lynx.getScreenshot call) so the native side receives them, and ensure any
listeners/streams are cleaned up on abort or completion.

---

Nitpick comments:
In `@packages/testing-library/kitten-lynx/src/KittenLynxView.ts`:
- Around line 366-370: Replace the manual disposal in the try/finally that
checks stream[Symbol.asyncDispose] with TypeScript 5's await using syntax: bind
the async-disposable stream with "await using" (e.g., await using const s =
stream) before the block that consumes it, use s inside the block, and remove
the finally block that calls stream[Symbol.asyncDispose](); ensure the code that
referenced stream now uses the new bound variable (stream -> s) and that your
tsconfig/target supports the "await using" feature so compilation succeeds.

In `@packages/testing-library/kitten-lynx/tests/lynx.spec.ts`:
- Around line 91-96: Replace the Promise-wrapped delays in the test with the
imported setTimeout from node:timers/promises: instead of awaiting new
Promise(resolve => setTimeout(resolve, 2000)), use await setTimeout(2000);
update the two occurrences in lynx.spec.ts (the delays before checking
`.Logo--react`/`.Logo--lynx` and after logoParent?.tap()) and ensure the module
import for setTimeout is present and not shadowed by any local variable.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 6b1ecf89-ecd1-4687-b9f8-3afc9798ffb8

📥 Commits

Reviewing files that changed from the base of the PR and between e119fa3 and 86338b5.

📒 Files selected for processing (3)

• .changeset/olive-readers-turn.md
• packages/testing-library/kitten-lynx/src/KittenLynxView.ts
• packages/testing-library/kitten-lynx/tests/lynx.spec.ts

[codspeed-hq]

Merging this PR will improve performance by 6.66%

⚠️ Different runtime environments detected

Some benchmarks with significant performance changes were compared across different runtime environments,
which may affect the accuracy of the results.

Open the report in CodSpeed to investigate

⚡ 2 improved benchmarks
✅ 70 untouched benchmarks
⏩ 3 skipped benchmarks¹

Performance Changes

	Benchmark	BASE	HEAD	Efficiency
⚡	basic-performance-div-100	7.3 ms	6.9 ms	+5.39%
⚡	basic-performance-nest-level-100	7.4 ms	6.9 ms	+6.66%

---

_{Comparing PupilTong:p/hw/kitten-lynx-more-apis (4d3668c) with main (4157823)}

Footnotes

1. 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]

Web Explorer

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

4d3668c(current) vs 4157823 main#8314(baseline)

Bundle metrics  no changes

	Current #8318	Baseline #8314
Initial JS	155.59KiB	155.59KiB
Initial CSS	35.1KiB	35.1KiB
Cache Invalidation	0%	0%
Chunks	8	8
Assets	8	8
Modules	238	238
Duplicate Modules	16	16
Duplicate Code	2.97%	2.97%
Packages	4	4
Duplicate Packages	0	0

Bundle size by type  no changes

	Current #8318	Baseline #8314
JS	254.26KiB	254.26KiB
Other	95.85KiB	95.85KiB
CSS	35.1KiB	35.1KiB

Bundle analysis report Branch PupilTong:p/hw/kitten-lynx-more-... Project dashboard

---

^{Generated by RelativeCI Documentation Report issue}

[coderabbitai]

Actionable comments posted: 1

♻️ Duplicate comments (1)

packages/testing-library/kitten-lynx/src/KittenLynxView.ts (1)

339-378: ⚠️ Potential issue | 🟠 Major

Prevent indefinite wait and forward declared screenshot options.

At Line 356, sendCDPStream is started without an abort signal, so the loop at Line 370 can block forever if no Lynx.screenshotCaptured arrives. Also, Line 366 sends params: {}, so format/quality from the public API are silently ignored.

🔧 Suggested patch

   async screenshot(options?: {
     path?: string;
     format?: 'jpeg' | 'png' | 'webp';
     quality?: number;
+    timeout?: number;
   }): Promise<Buffer> {
     const { ReadableStream } = await import('node:stream/web');
     const sessionId = (this._channel as any)._sessionId;
+    const timeout = options?.timeout ?? 30000;
+    const controller = new AbortController();
+    const timeoutId = globalThis.setTimeout(() => controller.abort(), timeout);

@@
     const stream = await this._connector.sendCDPStream(
       this._clientId,
       inputStream,
+      { signal: controller.signal },
     );

@@
       pushMessage({
         method: 'Lynx.getScreenshot',
-        params: {},
+        params: {
+          ...(options?.format ? { format: options.format } : {}),
+          ...(typeof options?.quality === 'number'
+            ? { quality: options.quality }
+            : {}),
+        },
         sessionId,
       });

@@
     } finally {
+      clearTimeout(timeoutId);
       closeStream();
       if (typeof stream[Symbol.asyncDispose] === 'function') {
         await stream[Symbol.asyncDispose]();
       }
     }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/testing-library/kitten-lynx/src/KittenLynxView.ts` around lines 339
- 378, The screenshot method starts sendCDPStream without an abort signal and
ignores the caller's options; update KittenLynxView.screenshot to create an
AbortController and pass its signal into this._connector.sendCDPStream so the
stream can be cancelled on timeout or on error/close, and ensure you call
controller.abort() (or closeStream) in the finally block to avoid indefinite
waiting; also forward the provided options (format, quality) from the public
screenshot signature into the pushed CDP message params instead of {} so the
remote side receives format/quality, and throw a clear error if no
Lynx.screenshotCaptured arrives within a reasonable timeout.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@packages/testing-library/kitten-lynx/src/KittenLynxView.ts`:
- Around line 344-346: The code currently dereferences this._channel as any to
read _sessionId (in the screenshot() flow) which can throw if no
attachment/session exists (e.g., screenshot() called before goto()); add an
explicit precondition check similar to locator() by verifying this._channel is
attached and has a valid _sessionId before reading it: if missing, throw a clear
Error indicating the attachment/session is required (mention screenshot() and
goto() in the message). Update the access site where ReadableStream and
sessionId are read (references: ReadableStream import, this._channel, and
_sessionId) to perform this guard and early error return.

---

Duplicate comments:
In `@packages/testing-library/kitten-lynx/src/KittenLynxView.ts`:
- Around line 339-378: The screenshot method starts sendCDPStream without an
abort signal and ignores the caller's options; update KittenLynxView.screenshot
to create an AbortController and pass its signal into
this._connector.sendCDPStream so the stream can be cancelled on timeout or on
error/close, and ensure you call controller.abort() (or closeStream) in the
finally block to avoid indefinite waiting; also forward the provided options
(format, quality) from the public screenshot signature into the pushed CDP
message params instead of {} so the remote side receives format/quality, and
throw a clear error if no Lynx.screenshotCaptured arrives within a reasonable
timeout.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: e8d2691f-4a5d-42fd-bf00-d229792a4be1

📥 Commits

Reviewing files that changed from the base of the PR and between 266567d and 4d3668c.

⛔ Files ignored due to path filters (1)

• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (7)

• .changeset/olive-readers-turn.md
• packages/testing-library/kitten-lynx/lynx.config.js
• packages/testing-library/kitten-lynx/package.json
• packages/testing-library/kitten-lynx/rslib.config.ts
• packages/testing-library/kitten-lynx/src/KittenLynxView.ts
• packages/testing-library/kitten-lynx/tests/lynx.spec.ts
• packages/testing-library/kitten-lynx/tsconfig.json

💤 Files with no reviewable changes (1)

• packages/testing-library/kitten-lynx/tsconfig.json

✅ Files skipped from review due to trivial changes (3)

• packages/testing-library/kitten-lynx/lynx.config.js
• packages/testing-library/kitten-lynx/package.json
• .changeset/olive-readers-turn.md

🚧 Files skipped from review as they are similar to previous changes (2)

• packages/testing-library/kitten-lynx/rslib.config.ts
• packages/testing-library/kitten-lynx/tests/lynx.spec.ts