touchpress 0.0.1 → 0.1.0

package/README.md

@@ -1,12 +1,12 @@
-# tangere
+# touchpress
 
 > [!WARNING]
-> tangere is highly experimental. Use at your own risk.
+> touchpress 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/).
+touchpress 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';
+import { expect, test } from 'touchpress';
 
 test('the right credentials land on the profile', async ({ device }) => {
   await device.getByTestId('sign-in-link').tap();
@@ -24,7 +24,7 @@ test('the right credentials land on the profile', async ({ device }) => {
 ### Install
 
 ```sh
-pnpm add -D tangere @playwright/test
+pnpm add -D touchpress @playwright/test
 ```
 
 ### Configure
@@ -32,9 +32,9 @@ pnpm add -D tangere @playwright/test
 ```ts
 // playwright.config.ts
 import { defineConfig } from '@playwright/test';
-import type { TangereOptions } from 'tangere';
+import type { TouchpressOptions } from 'touchpress';
 
-export default defineConfig<TangereOptions>({
+export default defineConfig<TouchpressOptions>({
   testDir: 'e2e',
   workers: 1,
   expect: { timeout: 10_000 },
@@ -50,9 +50,9 @@ export default defineConfig<TangereOptions>({
 });
 ```
 
-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.
+Every option touchpress 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.
+`readyWhen` is required. The driver returns from a launch as soon as the native process starts, before the JavaScript bundle has loaded, so touchpress 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.
 
@@ -64,11 +64,24 @@ One worker gets one device. To run more than one, give `deviceName` an array wit
 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.
+`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/touchpress/blob/main/docs/basics.md) has the spec, and [`apps/e2e/e2e/preflight.setup.mts`](https://github.com/wobsoriano/touchpress/blob/main/apps/e2e/e2e/preflight.setup.mts) is a working one.
+
+### Drive a step with a model
+
+`device.act` takes an instruction in English and drives the app until it is satisfied. `device.extract` asks one question about the screen and returns a typed answer.
+
+```ts
+test('sign in', async ({ device }) => {
+  await device.act('Sign in with the email rob@example.com and the password hunter2');
+  await expect(device.getByTestId('greeting')).toHaveText('Hi, Rob');
+});
+```
+
+Set `use.aiModel` to a gateway model id or a provider model instance, and install `ai`, an optional peer dependency. A loop can run for minutes, so raise the test timeout on any spec that calls `act`. The example uses the sample app's fake account. Keep real credentials in deterministic `fill(text, { secret: true })` calls outside `act`, and assert deterministically afterwards. [AI](https://github.com/wobsoriano/touchpress/blob/main/docs/ai.md) covers `act`, `extract`, the tools the model gets, and the report.
 
 ## 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`:
+`apps/e2e` is an Expo app with a home, login, and profile route and a fake sign-in. It is the app touchpress 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
@@ -89,18 +102,19 @@ 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)
+- [Basics](https://github.com/wobsoriano/touchpress/blob/main/docs/basics.md)
+- [Configuration](https://github.com/wobsoriano/touchpress/blob/main/docs/configuration.md)
+- [Locators](https://github.com/wobsoriano/touchpress/blob/main/docs/locators.md)
+- [Assertions](https://github.com/wobsoriano/touchpress/blob/main/docs/assertions.md)
+- [AI](https://github.com/wobsoriano/touchpress/blob/main/docs/ai.md)
+- [Lifecycle](https://github.com/wobsoriano/touchpress/blob/main/docs/lifecycle.md)
+- [Continuous integration](https://github.com/wobsoriano/touchpress/blob/main/docs/ci.md)
 
 ## The workspace
 
 ```
-packages/tangere/  the library, published to npm
-apps/e2e/          tangere-e2e, an Expo SDK 57 app, private
+packages/touchpress/  the library, published to npm
+apps/e2e/          touchpress-e2e, an Expo SDK 57 app, private
 docs/              the documentation linked above
 ```
 

package/dist/core/index.d.mts

@@ -1,4 +1,4 @@
-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";
+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 TOUCHPRESS_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 TouchpressOptions, l as ScrollTrail, lt as describeQuery, m as FillOptions, mt as RawSnapshot, n as PreflightReport, nt as Verdict, o as TouchpressError, 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-Czhj9QFM.mjs";
 //#region src/core/evidence.d.ts
 /**
  * Never throws. A capture that fails records a note and returns, because masking
@@ -68,4 +68,4 @@ declare function toPixelBox(rect: {
 /** 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 };
+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, TOUCHPRESS_DEFAULTS, type TextMatch, type TextOptions, TouchpressError, type TouchpressOptions, 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

@@ -1,2 +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 };
+import { A as textMatch, C as renderScreen, D as parseDeviceOptions, E as deviceNameForSlot, O as describeQuery, S as parseScreen, T as TOUCHPRESS_DEFAULTS, a as sizeOf, b as renderTitle, d as createScrollSearch, f as directionToward, g as sessionName, h as openSession, i as relativeTo, j as TouchpressError, 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 describeCheck, w as resolve, x as silentSink, y as evaluate } from "../preflight-B7KrbqSO.mjs";
+export { TOUCHPRESS_DEFAULTS, TouchpressError, 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

@@ -1,8 +1,43 @@
-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 { 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 TouchpressOptions$1, n as PreflightReport, o as TouchpressError, ot as Query, p as Device$1, pt as Platform, r as preflight, st as Role, t as PreflightDevice, vt as ScreenNode } from "./preflight-Czhj9QFM.mjs";
 import { ExpectMatcherState } from "@playwright/test";
+import { FlexibleSchema, LanguageModel } from "ai";
+//#region src/ai/device.d.ts
+/** A loop can run for minutes, so its budget is its own rather than the action timeout a deterministic step takes. */
+type ActOptions = {
+  timeout?: number;
+  maxSteps?: number;
+};
+type ExtractOptions = {
+  timeout?: number;
+};
+type AiDevice = {
+  /**
+   * Drives the app with a model until the instruction is satisfied. Resolves
+   * with the model's summary of what it did, and throws when the model reports
+   * it could not proceed or runs out of steps.
+   */
+  act(instruction: string, options?: ActOptions): Promise<string>;
+  /** Asks a model one question about the current screen and validates the answer against `schema`. */
+  extract<T>(question: string, schema: FlexibleSchema<T>, options?: ExtractOptions): Promise<T>;
+};
+//#endregion
+//#region src/ai/options.d.ts
+/**
+ * The one key `act` and `extract` add to Playwright's `use`. It is not part of
+ * `core/config.ts`, because nothing under `core/` may name an AI SDK type.
+ *
+ * A gateway model id such as `'anthropic/claude-sonnet-5'` and a provider
+ * model instance are both `LanguageModel`, so a config picks either without a
+ * second key. Unset is the default, and it fails at the first `act` rather than
+ * at worker start, so a project that never calls one needs no model.
+ */
+type AiOptions = {
+  aiModel: LanguageModel | undefined;
+};
+//#endregion
 //#region src/playwright/fixtures.d.ts
 /**
- * Tangere's options and none of its fixtures, for a setup project that reads the
+ * Touchpress'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
@@ -10,7 +45,7 @@ import { ExpectMatcherState } from "@playwright/test";
  * 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>;
+declare const setupTest: import("@playwright/test").TestType<import("@playwright/test").PlaywrightTestArgs & import("@playwright/test").PlaywrightTestOptions & object, import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions & TouchpressOptions$1 & AiOptions>;
 /**
  * `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,
@@ -21,8 +56,8 @@ declare const setupTest: import("@playwright/test").TestType<import("@playwright
  * `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 & {
+  device: Device$1 & AiDevice;
+}, import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions & TouchpressOptions$1 & AiOptions & {
   session: DeviceSession;
 }>;
 //#endregion
@@ -64,7 +99,7 @@ declare const expect: import("@playwright/test").Expect<{
   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<{
+  toHaveScreenshot(this: ExpectMatcherState, target: Device$1 | Locator, nameOrOptions?: string | ScreenshotOptions, options?: ScreenshotOptions): Promise<{
     pass: boolean;
     message: () => string;
     name: string;
@@ -73,4 +108,13 @@ declare const expect: import("@playwright/test").Expect<{
   }>;
 }>;
 //#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 };
+//#region src/index.d.ts
+/**
+ * `Device` and `TouchpressOptions` carry the AI surface here and only here.
+ * `touchpress/core` exports the runner-independent pair without it, because
+ * nothing under `core/` may name an AI SDK type.
+ */
+type TouchpressOptions = TouchpressOptions$1 & AiOptions;
+type Device = Device$1 & AiDevice;
+//#endregion
+export { type ActOptions, type AiDevice, type AiOptions, Device, type ErrorInfo, type ExpectedValue, type ExtractOptions, 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, type TextMatch, TouchpressError, TouchpressOptions, expect, preflight, setupTest, test };