touchpress 0.0.1

package/README.md

@@ -0,0 +1,111 @@
+# tangere
+
+> [!WARNING]
+> tangere is highly experimental. Use at your own risk.
+
+tangere runs e2e tests for mobile apps on the Playwright test runner. It drives a booted simulator or emulator through [`agent-device`](https://agent-device.dev/).
+
+```ts
+import { expect, test } from 'tangere';
+
+test('the right credentials land on the profile', async ({ device }) => {
+  await device.getByTestId('sign-in-link').tap();
+  await device.getByRole('text-field', { name: 'Email' }).fill('rob@example.com');
+  await device.getByTestId('password').fill('hunter2', { secret: true });
+  await device.getByRole('button', { name: 'Sign in' }).tap();
+
+  await expect(device.getByTestId('signing-in')).toBeVisible();
+  await expect(device.getByTestId('profile-email')).toHaveText('rob@example.com', { exact: true });
+});
+```
+
+## Usage
+
+### Install
+
+```sh
+pnpm add -D tangere @playwright/test
+```
+
+### Configure
+
+```ts
+// playwright.config.ts
+import { defineConfig } from '@playwright/test';
+import type { TangereOptions } from 'tangere';
+
+export default defineConfig<TangereOptions>({
+  testDir: 'e2e',
+  workers: 1,
+  expect: { timeout: 10_000 },
+  reporter: [['list'], ['html', { open: 'never' }]],
+  use: {
+    app: 'com.example.app',
+    readyWhen: { testId: 'home' },
+  },
+  projects: [
+    { name: 'ios', use: { platform: 'ios', deviceName: 'iPhone 17 Pro Max' } },
+    { name: 'android', use: { platform: 'android', deviceName: 'Pixel 7 API 34' } },
+  ],
+});
+```
+
+Every option tangere adds is a key of its own in `use`. Playwright merges `use` one key at a time, so what the projects share is written once at the top level and a project sets only what differs.
+
+`readyWhen` is required. The driver returns from a launch as soon as the native process starts, before the JavaScript bundle has loaded, so tangere waits for that locator before the first test runs.
+
+`deviceName` is what `agent-device devices` prints, which for an Android emulator is the AVD name with its underscores shown as spaces. An AVD created as `Pixel_7_API_34` is `Pixel 7 API 34` here.
+
+One worker gets one device. To run more than one, give `deviceName` an array with an entry per worker.
+
+### Run
+
+```sh
+npx playwright test --project=ios
+```
+
+`preflight` reads a project's options and reports whether the device they name is booted, so a missing simulator fails once, in about a second, instead of once per test after the launch timeout. Wire it as a setup project per platform that the device projects depend on. [Basics](https://github.com/wobsoriano/tangere/blob/main/docs/basics.md) has the spec, and [`apps/e2e/e2e/preflight.setup.mts`](https://github.com/wobsoriano/tangere/blob/main/apps/e2e/e2e/preflight.setup.mts) is a working one.
+
+## Run the sample project
+
+`apps/e2e` is an Expo app with a home, login, and profile route and a fake sign-in. It is the app tangere is tested against. Build the library first with `vp run -r build` so the app can resolve `dist`, then run these from `apps/e2e`:
+
+```sh
+npx expo run:ios --device 'iPhone 17 Pro Max' --no-bundler
+npx expo start --port 8081
+npx playwright test --project=ios
+```
+
+Android works the same way. `expo run:android` takes the AVD's own name with underscores, not the spaced name the test config uses, and the emulator needs `adb reverse` to reach Metro on the host.
+
+```sh
+npx expo run:android --device Expo_API_36 --no-bundler
+adb reverse tcp:8081 tcp:8081
+npx expo start --port 8081
+npx playwright test --project=android
+```
+
+Leave Metro running for the whole suite. The first build takes several minutes.
+
+## Docs
+
+- [Basics](https://github.com/wobsoriano/tangere/blob/main/docs/basics.md)
+- [Configuration](https://github.com/wobsoriano/tangere/blob/main/docs/configuration.md)
+- [Locators](https://github.com/wobsoriano/tangere/blob/main/docs/locators.md)
+- [Assertions](https://github.com/wobsoriano/tangere/blob/main/docs/assertions.md)
+- [Lifecycle](https://github.com/wobsoriano/tangere/blob/main/docs/lifecycle.md)
+- [Continuous integration](https://github.com/wobsoriano/tangere/blob/main/docs/ci.md)
+
+## The workspace
+
+```
+packages/tangere/  the library, published to npm
+apps/e2e/          tangere-e2e, an Expo SDK 57 app, private
+docs/              the documentation linked above
+```
+
+`vp check`, `vp test`, and `vp run -r build` at the root cover every package. The end-to-end suite is separate because it needs a device.
+
+## License
+
+MIT

package/dist/core/index.d.mts

@@ -0,0 +1,71 @@
+import { $ as Tree, A as deviceNameForSlot, B as ProbeResult, C as openSession, D as ResolvedOptions, E as ReadyQuery, F as StepOptions, G as CaptureOptions, H as formatFailure, I as Typed, J as DeviceInfo, K as DeviceDriver, L as renderTitle, M as ActionRecord, N as ActionSink, O as TANGERE_DEFAULTS, P as EvidenceFile, Q as Settled, R as silentSink, S as SessionState, T as DeviceChoice, U as probe, V as ProbeTarget, W as Binding, X as OpenRequest, Y as DeviceSelection, Z as ScrollDirection, _ as RoleOptions, _t as Screen, a as ExpectedValue, at as Filter, b as DeviceSession, bt as renderScreen, c as ScrollSearch, ct as TextMatch, d as directionToward, dt as textMatch, et as Check, f as ActionOptions, ft as PinnedRef, g as Locator, gt as Resolution, h as FilterOptions, ht as Rect, i as ErrorInfo, it as evaluate, j as parseDeviceOptions, k as TangereOptions, l as ScrollTrail, lt as describeQuery, m as FillOptions, mt as RawSnapshot, n as PreflightReport, nt as Verdict, o as TangereError, ot as Query, p as Device, pt as Platform, q as DeviceFailure, r as preflight, rt as describeCheck, s as ScrollDevice, st as Role, t as PreflightDevice, tt as CheckName, u as createScrollSearch, ut as normalizeText, v as TextOptions, vt as ScreenNode, w as sessionName, x as OpenSessionInput, xt as resolve, y as createDevice, yt as parseScreen, z as ProbeOptions } from "../preflight--Z-REtl-.mjs";
+//#region src/core/evidence.d.ts
+/**
+ * Never throws. A capture that fails records a note and returns, because masking
+ * the test's real error with a screenshot error is worse than no screenshot.
+ */
+declare function captureEvidence(session: DeviceSession, sink: ActionSink): Promise<void>;
+//#endregion
+//#region src/core/screenshot.d.ts
+/** A rectangle in image pixels, which is what a snapshot rect becomes once it is scaled. */
+type PixelBox = {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+};
+type Size = {
+  readonly width: number;
+  readonly height: number;
+};
+type CompareOptions = {
+  /** pixelmatch's per-pixel colour distance, 0 to 1. Smaller is stricter. */
+  readonly threshold: number;
+  /** The share of the image allowed to differ before the comparison fails. */
+  readonly maxDiffPixelRatio: number;
+  /**
+   * Painted opaque black in both images before anything is compared. A clock, an
+   * avatar, or anything else that changes between runs goes here rather than
+   * into a looser threshold, which would blind the whole image.
+   */
+  readonly mask: readonly PixelBox[];
+};
+/**
+ * A size mismatch is its own case rather than a ratio of 1, because nothing
+ * about a threshold or a mask can rescue it.
+ */
+type Comparison = {
+  readonly kind: 'match';
+  readonly ratio: number;
+} | {
+  readonly kind: 'mismatch';
+  readonly ratio: number;
+  readonly diff: Buffer;
+} | {
+  readonly kind: 'size-mismatch';
+  readonly expected: Size;
+  readonly actual: Size;
+};
+/**
+ * The ratio is mismatched pixels over the image's own pixel count, so it means
+ * the same whether the images are a whole device or one cropped button.
+ */
+declare function compareScreenshot(expected: Buffer, actual: Buffer, options: CompareOptions): Comparison;
+/**
+ * The box is clamped to the image, because a rect comes from a snapshot and a
+ * screenshot is a separate capture. A control flush against the bottom edge can
+ * round a pixel past it, and that is not a reason to fail an assertion.
+ */
+declare function cropScreenshot(source: Buffer, box: PixelBox): Buffer;
+declare function sizeOf(source: Buffer): Size;
+/** Rounded outward, so a control's own edge is never the thing that gets cut off. */
+declare function toPixelBox(rect: {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}, scale: number): PixelBox;
+/** Moves a box into the coordinates of a crop taken at `origin`. */
+declare function relativeTo(box: PixelBox, origin: PixelBox): PixelBox;
+//#endregion
+export { type ActionOptions, type ActionRecord, type ActionSink, type Binding, type CaptureOptions, type Check, type CheckName, type CompareOptions, type Comparison, type Device, type DeviceChoice, type DeviceDriver, type DeviceFailure, type DeviceInfo, type DeviceSelection, type DeviceSession, type ErrorInfo, type EvidenceFile, type ExpectedValue, type FillOptions, type Filter, type FilterOptions, type Locator, type OpenRequest, type OpenSessionInput, type PinnedRef, type PixelBox, type Platform, type PreflightDevice, type PreflightReport, type ProbeOptions, type ProbeResult, type ProbeTarget, type Query, type RawSnapshot, type ReadyQuery, type Rect, type Resolution, type ResolvedOptions, type Role, type RoleOptions, type Screen, type ScreenNode, type ScrollDevice, type ScrollDirection, type ScrollSearch, type ScrollTrail, type SessionState, type Settled, type Size, type StepOptions, TANGERE_DEFAULTS, TangereError, type TangereOptions, type TextMatch, type TextOptions, type Tree, type Typed, type Verdict, captureEvidence, compareScreenshot, createDevice, createScrollSearch, cropScreenshot, describeCheck, describeQuery, deviceNameForSlot, directionToward, evaluate, formatFailure, normalizeText, openSession, parseDeviceOptions, parseScreen, preflight, probe, relativeTo, renderScreen, renderTitle, resolve, sessionName, silentSink, sizeOf, textMatch, toPixelBox };

package/dist/core/index.mjs

@@ -0,0 +1,2 @@
+import { A as textMatch, C as describeCheck, D as parseDeviceOptions, E as deviceNameForSlot, O as describeQuery, S as resolve, T as TANGERE_DEFAULTS, a as sizeOf, b as parseScreen, d as createScrollSearch, f as directionToward, g as sessionName, h as openSession, i as relativeTo, j as TangereError, k as normalizeText, l as captureEvidence, m as probe, n as compareScreenshot, o as toPixelBox, p as formatFailure, r as cropScreenshot, t as preflight, u as createDevice, v as renderTitle, w as evaluate, x as renderScreen, y as silentSink } from "../preflight-C83jCNPs.mjs";
+export { TANGERE_DEFAULTS, TangereError, captureEvidence, compareScreenshot, createDevice, createScrollSearch, cropScreenshot, describeCheck, describeQuery, deviceNameForSlot, directionToward, evaluate, formatFailure, normalizeText, openSession, parseDeviceOptions, parseScreen, preflight, probe, relativeTo, renderScreen, renderTitle, resolve, sessionName, silentSink, sizeOf, textMatch, toPixelBox };

package/dist/index.d.mts

@@ -0,0 +1,76 @@
+import { E as ReadyQuery, _t as Screen, a as ExpectedValue, at as Filter, b as DeviceSession, ct as TextMatch, g as Locator, h as FilterOptions, ht as Rect, i as ErrorInfo, k as TangereOptions, n as PreflightReport, o as TangereError, ot as Query, p as Device, pt as Platform, r as preflight, st as Role, t as PreflightDevice, vt as ScreenNode } from "./preflight--Z-REtl-.mjs";
+import { ExpectMatcherState } from "@playwright/test";
+//#region src/playwright/fixtures.d.ts
+/**
+ * Tangere's options and none of its fixtures, for a setup project that reads the
+ * configuration before any session exists, such as one calling `preflight`.
+ *
+ * `platform`, `app`, and `readyWhen` default to `undefined` rather than to a
+ * plausible value. A Playwright option fixture needs a default of its declared
+ * type, and `parseDeviceOptions` rejects `undefined` by name, so a config that
+ * forgot a key and one that never set it fail the same way.
+ */
+declare const setupTest: import("@playwright/test").TestType<import("@playwright/test").PlaywrightTestArgs & import("@playwright/test").PlaywrightTestOptions & object, import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions & TangereOptions>;
+/**
+ * `device` is auto so evidence capture runs for every test in a device project,
+ * whether or not the body touched it. Its teardown runs before the session's,
+ * inside the separate budget Playwright grants after the test finishes, so a
+ * timed-out test still gets a screenshot.
+ *
+ * Importing and extending `test` launches no browser: `browser`, `context`, and
+ * `page` are lazy and non-auto, and nothing here names them.
+ */
+declare const test: import("@playwright/test").TestType<import("@playwright/test").PlaywrightTestArgs & import("@playwright/test").PlaywrightTestOptions & object & {
+  device: Device;
+}, import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions & TangereOptions & {
+  session: DeviceSession;
+}>;
+//#endregion
+//#region src/playwright/screenshot.d.ts
+type ScreenshotOptions = {
+  timeout?: number;
+  /** The share of the image allowed to differ. @default 0.01 */
+  maxDiffPixelRatio?: number;
+  /** pixelmatch's per-pixel colour distance, 0 to 1. Smaller is stricter. @default 0.2 */
+  threshold?: number;
+  /** Painted opaque black in both images, for anything that legitimately changes between runs. */
+  mask?: Locator[];
+};
+//#endregion
+//#region src/playwright/expect.d.ts
+type MatcherOptions = {
+  timeout?: number;
+};
+type TextMatcherOptions = MatcherOptions & {
+  exact?: boolean;
+};
+type MatcherResult = {
+  pass: boolean;
+  message: () => string;
+  name: string;
+  expected: string;
+  actual: string | null;
+};
+/**
+ * Playwright's own matcher names on this package's `expect` only. Matcher
+ * typing is by the first parameter, so these surface on `expect(locator)` and
+ * nothing else.
+ */
+declare const expect: import("@playwright/test").Expect<{
+  toBeVisible: (this: ExpectMatcherState, locator: Locator, options?: MatcherOptions) => Promise<MatcherResult>;
+  toBeEnabled: (this: ExpectMatcherState, locator: Locator, options?: MatcherOptions) => Promise<MatcherResult>;
+  toBeSelected: (this: ExpectMatcherState, locator: Locator, options?: MatcherOptions) => Promise<MatcherResult>;
+  toBeFocused: (this: ExpectMatcherState, locator: Locator, options?: MatcherOptions) => Promise<MatcherResult>;
+  toHaveText(this: ExpectMatcherState, locator: Locator, expected: string | RegExp, options?: TextMatcherOptions): Promise<MatcherResult>;
+  toHaveValue(this: ExpectMatcherState, locator: Locator, expected: string | RegExp, options?: MatcherOptions): Promise<MatcherResult>;
+  toHaveCount(this: ExpectMatcherState, locator: Locator, expected: number, options?: MatcherOptions): Promise<MatcherResult>;
+  toHaveScreenshot(this: ExpectMatcherState, target: Device | Locator, nameOrOptions?: string | ScreenshotOptions, options?: ScreenshotOptions): Promise<{
+    pass: boolean;
+    message: () => string;
+    name: string;
+    expected: string;
+    actual: string | null;
+  }>;
+}>;
+//#endregion
+export { type Device, type ErrorInfo, type ExpectedValue, type Filter, type FilterOptions, type Locator, type Platform, type PreflightDevice, type PreflightReport, type Query, type ReadyQuery, type Rect, type Role, type Screen, type ScreenNode, type ScreenshotOptions, TangereError, type TangereOptions, type TextMatch, expect, preflight, setupTest, test };