@toloka-platform/sdk 0.1.0-preview.6 → 0.1.0-preview.8

package/dist/cli/toloka.js.jsc.sha256

@@ -1 +1 @@
-2e4e22afc766a0a267262fe07718505b43f1cdf364e402a990279e224ad92923  toloka.js.jsc
+ce1d79afa2e57b085b55b98cf5c4cb90ab84b8a6ba50e586586f208a70f7f088  toloka.js.jsc

package/dist/cli/toloka.js.sha256

@@ -1 +1 @@
-842c3cdfb47d5a899375c288cefa8ba550c22301dbd47d99d224a8b34acd01a2  toloka.js
+44e401115084c2e912fe03234c4104090d1698c95e170f16cac9c4505952709a  toloka.js

package/docs/authoring.md

@@ -61,10 +61,8 @@ import { code } from "@toloka-platform/sdk";
 export const orderFaces = code("order_faces", {
   about: { name: "order_faces", description: "Sort annotations top-left to bottom-right." },
   envVars: [],
-  fieldProxies: {
-    input: [{ field: draftFaces, optional: false }],
-    output: [{ field: faces, optional: false }],
-  },
+  input: [{ field: draftFaces, optional: false }],
+  output: [{ field: faces, optional: false }],
   code: {
     code: `from main_types import Inputs, Outputs
 
@@ -77,6 +75,8 @@ async def main(inputs: Inputs) -> Outputs:
 
 If the program calls an external service, list the secret names in `envVars`. The sandbox has no ambient environment.
 
+Register authored code behavior with `test.code(pipeline, node, name, callback)` from `@toloka-platform/sdk/testing`, execute its bound `run` helper, and cover representative inputs, boundaries, deterministic behavior, and real failures. Bare `runCodeNode` calls remain useful for exploratory tests but do not satisfy `toloka check` coverage.
+
 ### generation
 
 One human-work task type. The node owns the entire expert journey: instruction, UI, entity schemas, quality criteria, quality assurance, audience, pricing, Training, and Exam.
@@ -132,6 +132,8 @@ export const annotateFaces = generation("annotate_faces", {
 });
 ```
 
+Test the interface locally before applying it. The SDK's Vitest fixture renders this exact `ui` block in Chromium, interacts with Fields by `path`, runs postprocess, validates output entities, and saves screenshots. See [Test pipelines locally](./testing.md).
+
 ### quorum
 
 The same item labeled by N independent people, with disagreement preserved. Every output field becomes a top-level array with one element per labeler.
@@ -144,13 +146,22 @@ export const ratePair = quorum("rate_pair", {
   publicName: "Rate the pair",
   overlap: 3,
   entities: {
-    input: [{ field: pairUrl, entityType: "TEXT" }],
-    output: [{ field: verdict, entityType: "TEXT" }],
+    input: [{ field: pairUrl, entityType: "CONTEXT" }],
+    output: [
+      {
+        field: verdict,
+        entityType: "SINGLE_LABEL",
+        allowedLabels: [
+          { label: "First video", value: "first" },
+          { label: "Second video", value: "second" },
+        ],
+      },
+    ],
   },
   qualityCriteria: [],
   instruction: "Pick the better of the two videos.",
   ui: {
-    code: "<></>",
+    code: "<View.Card><Field.RadioGroup path={'verdict'} label={'Better video'} options={[{ label: 'First video', value: 'first' }, { label: 'Second video', value: 'second' }]} validation={[{ required: true }]} /></View.Card>",
     data: "{}",
     preprocess: "return {}",
     postprocess: "return {};",
@@ -197,7 +208,7 @@ export const routeDisputed = match("route_disputed", {
       predicates: [{ field: verdict, jsonPath: "$", operator: "text_eq", value: "disputed" }],
     },
   ],
-  fieldProxies: { input: [{ field: verdict, optional: false }] },
+  input: [{ field: verdict, optional: false }],
 });
 ```
 
@@ -258,7 +269,7 @@ Never hand-write `fp_…`, `ds.…`, `pl.…`, or `pp.…` values into settings,
 ## Validate
 
 ```sh
-bunx tsc --noEmit
+toloka check
 toloka validate
 ```
 

package/docs/cli-v2.md

@@ -9,8 +9,8 @@ The platform object is a **project** (`pp.…`, today's pipeline project). Windm
 Today the checkout is a pipeline tree that happens to mention a project.
 
 - A directory is a project root if it has `toloka.json` **or** a `pipelines/` folder. No pipelines, no root.
-- `init` writes agent skills before a project exists; if one is already selected, it also binds the directory.
-- A checkout attaches when `project create` or `import` writes `toloka.json`, or when `init` finds an already selected project.
+- `init` writes agent skills before a project exists. It writes `toloka.json` only from an explicit `--project-id`, `TOLOKA_PROJECT_ID` / `POTATO_PROJECT_ID`, or an existing checkout; it never binds a new checkout from the machine registry.
+- A checkout attaches when `project create` or `import` writes `toloka.json`, or when `init` receives explicit project identity.
 - `run`, `status`, `runs`, and `cost` pick a pipeline from `toloka.json`. Zero pipelines is an error. Several pipelines opens a picker. The command names pretend there is "the" pipeline.
 - `status` means "latest run of some pipeline", not "this project".
 
@@ -106,7 +106,7 @@ UI links follow the resource-first shape `toloka <resource> url`. `project url`
 toloka init
 ```
 
-It writes the agent entry points without calling the platform. When a project is already selected, it also writes `toloka.json` with empty bindings. It does not require `pipelines/`; `project create` creates the live project.
+It writes the agent entry points without calling the platform. It never binds a new checkout from the machine registry. With an explicit `--project-id` or project-id environment variable, it also writes `toloka.json` with empty bindings. It does not require `pipelines/`; `project create` creates the live project.
 
 `import` stays the "pull an existing live project into this checkout" path. After v2 it uses the selected project when the id is omitted:
 

package/docs/cli.md

@@ -4,8 +4,7 @@ The `toloka` CLI reads TypeScript source as the desired state, compares it with
 
 This CLI is Preview software. Commands, flags, and output can change without a major version bump.
 
-`toloka` requires Bun. The binary declares a `bun` shebang and the package ships TypeScript source with no
-build step, so it does not run under plain Node.
+`toloka` requires Bun 1.4.0. The published package ships matching CLI bytecode; the launcher falls back to TypeScript source in a development checkout when the bytecode is absent.
 
 ## Configuration
 
@@ -33,6 +32,8 @@ Credentials and the platform base URL resolve from the same precedence order, hi
 
 `toloka login` verifies the key against the platform before saving anything. It writes `$XDG_CONFIG_HOME/toloka/credentials.json`, which defaults to `~/.config/toloka/credentials.json`, with file mode `0600` and a parent directory with mode `0700`. The file may also store local project aliases. The legacy `~/.toloka/credentials.json` is still read when the new path has no file. `toloka logout` deletes the stored file but does not revoke the key.
 
+Machine settings live next to that credentials file in `settings.json` and default `auto-update` to `true`. A globally installed `toloka` checks `https://registry.npmjs.org/` at most once per day and, when a newer `@toloka-platform/sdk` version has been published for at least 24 hours, installs it with `bun add --global` and re-runs the original command. The check is pinned to that registry; a checkout `.env` cannot retarget it. `config`, `version`, and `help` never trigger a check. Project-local installs, CI, and `TOLOKA_SKIP_AUTO_UPDATE=1` also skip it. `TOLOKA_AUTO_UPDATE=0` turns it off for one command; `TOLOKA_AUTO_UPDATE=1` turns it on even when the setting is false.
+
 Ordinary usage events (`sdk_cli_command_completed` / `sdk_cli_command_failed`) go to Toloka's PostHog project so we can see which commands run and which error classes they hit. Their payloads contain only an allowlisted command classifier, duration, exit code, outcome or error code, SDK and Bun versions, actor, and channel. Raw arguments, flag values, environment variables, API keys, secret names, base URLs and hosts, local paths, project ids, error messages, stack traces, and source context are not sent. GeoIP enrichment is disabled. Distinct id starts as a random UUID stored next to the credentials file. After a successful authenticated command, the CLI calls `GET /me` and aliases that UUID onto the platform user id without setting person properties. Set `TOLOKA_TELEMETRY=0` or `DO_NOT_TRACK=1` to disable capture. CI environments are disabled unless `TOLOKA_TELEMETRY=1`. The explicitly approved full-text `report` event is documented in [report](#report).
 
 The root program accepts these flags before any command:
@@ -65,7 +66,7 @@ Resources may also expose specialized actions beyond the Base Actions, such as `
 Register and select the platform project later commands use.
 
 ```sh
-toloka project list
+toloka project list [--limit <n>]
 toloka project add [alias] [projectId]
 toloka project switch <alias>
 toloka project current
@@ -108,6 +109,19 @@ toloka auth-status [--show-token]
 
 On success it prints the platform URL with its source, the API key masked unless `--show-token` is passed, the selected project, and `Reachable: N project(s) visible.` The project line is printed even when no key is in effect or the platform is not reachable. It exits `1` when no key is in effect or the platform is not reachable.
 
+## config
+
+Reads and writes machine CLI settings. The only setting today is `auto-update`, which defaults to `true`.
+
+```sh
+toloka config
+toloka config get
+toloka config get auto-update
+toloka config set auto-update false
+```
+
+`config` and `config get` with no name print `auto-update=true` or `auto-update=false`. `config get auto-update` prints only the boolean. `config set auto-update <value>` accepts `true` / `false` / `1` / `0` / `on` / `off` / `yes` / `no` and prints `Set auto-update to <boolean>.` Unknown names and values exit `1`.
+
 ## init
 
 Initializes the current project directory and installs the Agent Bootstrap entry points.
@@ -152,15 +166,29 @@ toloka validate
 
 On success it prints one line per pipeline: `valid`, `invalid` with issue details, or `skipped` when the pipeline is not on the platform yet. Exits `1` when any submitted graph is invalid.
 
+## check
+
+Runs the complete local gate without platform credentials.
+
+```sh
+toloka check [pipeline] [--node <name-or-id>] [--json] [--watch]
+```
+
+The command loads authored source, runs the project's TypeScript compiler, typechecks every Task UI against declarations bundled with the installed SDK, runs Vitest, and compares passing typed test evidence with every code node, human-work node, and pipeline. Statuses distinguish `missing`, `failed`, `partial`, and `infrastructure_error`. Exit code `0` means all required checks passed, `1` means source, types, tests, or required coverage failed, and `2` means a required checker could not run.
+
+Use `test.code`, `test.ui`, and `test.pipeline` from `@toloka-platform/sdk/testing` to produce required evidence. Plain Vitest tests still run and can fail the command, but do not satisfy graph coverage. A focused check accepts a pipeline plus `--node`; `--watch` serializes reruns after relevant file changes.
+
+With `--watch`, the command prints one complete report after each serialized run. With `--watch --json`, each report is one JSON line.
+
 ## apply
 
-Makes the platform match source.
+Runs the complete Local Check Gate, then makes the platform match source.
 
 ```sh
 toloka apply
 ```
 
-A preflight pass refuses before any write when a pipeline or dataset is removed from source, a project secret is missing, or a dataset field schema conflicts. On success it prints `No changes.` or `Applied N writes to project <projectId>.`
+Checks run before credentials are resolved or any platform request is made. A failed or missing required check exits `1`; a checker infrastructure error exits `2`. After a pass, the preflight refuses before any write when a pipeline or dataset is removed from source, a project secret is missing, or a dataset field schema conflicts. On success it prints `No changes.` or `Applied N writes to project <projectId>.`
 
 ## secret set
 
@@ -187,7 +215,7 @@ On success it prints the project id and name, team id, live counts, and either `
 Operate on a live pipeline in the selected project. Name or id is required unless a TTY picker can choose among several live pipelines. There is no implicit "the only pipeline."
 
 ```sh
-toloka pipeline list
+toloka pipeline list [--limit <n>]
 toloka pipeline run [name] [--wait] [--timeout <ms>]
 toloka pipeline status [name]
 toloka pipeline runs [name] [--limit <n>]
@@ -282,21 +310,21 @@ After an SDK upgrade `list` reports installed skills whose catalog digest change
 
 `toloka pipeline run --wait` maps the run outcome to the process exit code.
 
-| Code | Meaning                                       |
-| ---- | --------------------------------------------- |
-| 0    | Run succeeded (terminal state)                |
-| 1    | Run failed (terminal state)                   |
-| 2    | Run still running when the wait window closed |
+| Code | `pipeline run --wait`                           | `check` / apply local gate                        |
+| ---- | ----------------------------------------------- | ------------------------------------------------- |
+| 0    | Run succeeded, or was accepted without `--wait` | All required local checks passed                  |
+| 1    | Run failed                                      | Source, types, tests, or required coverage failed |
+| 2    | Run remained active when the wait window closed | A required checker could not run                  |
 
-Without `--wait`, exit code `0` means only that the run was accepted. Every other failure exits non-zero with a message on stderr: missing `toloka.json`, a rejected login, an unauthenticated `auth-status`, or a failed `secret set`.
+Every other failure exits non-zero with a message on stderr: missing project identity, a rejected login, an unauthenticated `auth-status`, or a failed `secret set`.
 
 ## The reconcile loop
 
-Treat the TypeScript source as authoritative. The canonical sequence is: typecheck, validate against the platform, plan, apply, then plan again to confirm convergence.
+Treat the TypeScript source as authoritative. The canonical sequence is: run the complete local gate, validate against the platform, plan, apply, then plan again to confirm convergence.
 
 ```sh
-# 1. Typecheck the project
-bun run typecheck
+# 1. Run source, type, and typed test checks
+toloka check
 
 # 2. Validate each bound pipeline against the platform
 toloka validate
@@ -311,7 +339,7 @@ toloka apply
 toloka plan  # expect: No changes.
 ```
 
-`toloka validate` posts each authored graph to `POST /pipelines/:pipelineId/graph/validate`. It runs platform spec validation and reports the latest matching check jobs. It does not write the graph. A pipeline that is not on the platform yet is skipped until `toloka apply` creates it. Resolve every unexpected plan change, missing secret, and immutable-field conflict before applying.
+`toloka apply` reruns the complete local gate before resolving credentials. `toloka validate` posts each authored graph to `POST /pipelines/:pipelineId/graph/validate`; it reports platform spec validation and the latest matching Remote Node Check jobs without writing the graph. Resolve every unexpected plan change, missing secret, and immutable-field conflict before applying.
 
 ## Further reading
 

package/docs/getting-started.md

@@ -4,14 +4,7 @@ Install the SDK, sign in, and get a pipeline project reconciling from source in
 
 ## Install
 
-The package is not published to npm yet. Link it from a checkout of this repository:
-
-```sh
-cd packages/sdk && bun link
-cd /path/to/your/project && bun link @toloka-platform/sdk
-```
-
-Declare the dependency in `package.json` so `toloka init` recognizes it. Once the hosted installer is deployed, install the bytecode-cached CLI and add the SDK to the project:
+Install the bytecode-cached CLI globally and declare the Preview SDK in the project:
 
 ```sh
 curl -fsSL https://platform.toloka.ai/cli/install.sh | sh
@@ -44,6 +37,8 @@ CI does not need `login`. Set `POTATO_API_KEY` and the stored file is ignored. S
 
 ## Start with an agent
 
+For a guided first run, start a fresh coding-agent session and ask it to follow `https://platform.toloka.ai/onboarding.md`. The guide takes the agent through installation, credentials, project selection, local tests, plan approval, apply, cost review, and a bounded sample run.
+
 Initialize the current directory and install the Agent Bootstrap. No platform project needs to be selected yet.
 
 ```sh
@@ -54,7 +49,7 @@ Open your coding agent in this directory and describe the project you want, for
 
 > Create a Toloka project that collects captions for images. Show me the plan before applying it.
 
-The bootstrap directs the agent to `toloka --help` and to search and install the matching bundled skill; the `toloka-build` skill then guides the agent through creating and selecting the platform project, authoring the TypeScript source, validating it, showing the plan, and applying the approved changes. `toloka.json` is created when the project is selected.
+The bootstrap directs the agent to `toloka --help` and to search and install the matching bundled skill; the `toloka-build` skill then guides the agent through creating and binding the platform project, authoring the TypeScript source, validating it, showing the plan, and applying the approved changes. `project create`, `import`, or explicit project identity on `init` writes `toloka.json`.
 
 ## Manual project setup
 
@@ -65,8 +60,8 @@ You are either adopting a project that already exists on the platform, or creati
 ```sh
 mkdir my-project && cd my-project
 toloka project add cats pp.019ffa5f-29a7-74de-a76c-7ba5ceedf37f
+toloka import pp.019ffa5f-29a7-74de-a76c-7ba5ceedf37f
 toloka init
-toloka import
 ```
 
 `import` writes a `pipelines/` tree and a `toloka.json` that maps your source to live IDs. If `pipelines/` already exists, pass `--force` to replace it. Read the generated TypeScript: it is the same shape you will edit from now on.
@@ -90,10 +85,10 @@ Then create `pipelines/<name>/pipeline.ts` with a default export and run `plan`
 
 ## The loop you will live in
 
-Every change follows the same steps. `validate`, `plan`, and `apply` talk to the platform.
+Every change follows the same steps. `toloka check` is credential-free; `validate`, `plan`, and `apply` talk to the platform. Apply reruns the complete local gate before any platform request.
 
 ```sh
-bunx tsc --noEmit
+toloka check
 toloka validate
 toloka plan
 toloka apply

package/docs/limitations.md

@@ -2,22 +2,22 @@
 
 What this Preview SDK does not do yet, stated plainly so you can decide what to depend on.
 
-`@toloka-platform/sdk` is `0.1.0-preview.6`. This is a Preview: the authoring API, the CLI surface, and the generated source layout can change without a major version bump. Pin an exact version. Do not depend on this in production yet.
+`@toloka-platform/sdk` is `0.1.0-preview.8`. This is a Preview: the authoring API, the CLI surface, and the generated source layout can change without a major version bump. Pin an exact version. Do not depend on this in production yet.
 
-## The SDK does not certify deployability
+## Local checks do not certify deployability
 
-`toloka validate` posts each bound graph to the platform and reports spec errors, warnings, and the latest matching check jobs. It does not write the graph.
+`toloka check` is the required credential-free local gate. It runs project TypeScript, automatic Task UI typechecking, Vitest, and typed node and pipeline-flow coverage. `toloka apply` reruns it before any platform write.
 
-A successful validate, and a successful `apply`, are still not proof that the pipeline can be launched. Gates that live outside that report are invisible to the CLI:
+`toloka validate` separately posts each bound graph to the platform and reports spec errors, warnings, and the latest matching Remote Node Check jobs. It does not write the graph. A passing local gate and platform validation are still not proof that the pipeline can launch:
 
 | gate                                              | where it is enforced | what the CLI tells you |
 | ------------------------------------------------- | -------------------- | ---------------------- |
 | Training course content, when Training is enabled | platform validation  | nothing                |
 | labeler UI validation receipt                     | platform validation  | nothing                |
 
-## Node checks are reported, not started
+The typed client can list, start, and poll Remote Node Checks. `toloka check` does not start them: it validates the authored source and its local tests. A `not_ran_node_check` result from `toloka validate` describes remote state, not missing local evidence.
 
-`toloka validate` includes the latest matching check jobs for the submitted graph. The typed client can list, start, and poll checks, but there is no `toloka check` command that discovers check contracts, configures cases, starts each required lint, waits, and explains reports. Configure and start missing checks in the platform UI for now.
+Python code nodes have executable behavior checks but no useful static Python typecheck yet. Their generated `Inputs` and `Outputs` aliases are currently `dict[str, Any]`; adding Pyright or mypy before those aliases become field-derived `TypedDict` contracts would provide little protection.
 
 ## Layout is not authored
 

package/docs/testing-examples.md

@@ -0,0 +1,248 @@
+# Pipeline testing examples
+
+Import the ready-to-use Vitest helpers from `@toloka-platform/sdk/testing`. The same entry point executes authored Python code nodes and renders human-work Task UIs in an isolated Chromium context.
+
+## Code node scenarios
+
+```ts
+import { expect, test } from "@toloka-platform/sdk/testing";
+import pipeline from "../../pipeline";
+import { classify } from "./node";
+
+const scenarios = [
+  { text: "A refund was requested", expected: "billing" },
+  { text: "The app crashes", expected: "technical" },
+];
+
+for (const scenario of scenarios) {
+  test.code(pipeline, classify, `classifies ${scenario.text}`, async ({ run }) => {
+    await expect(run({ text: scenario.text })).resolves.toEqual({ category: scenario.expected });
+  });
+}
+
+test.code(pipeline, classify, "surfaces authored failures", async ({ run }) => {
+  await expect(run({ text: "" })).rejects.toMatchObject({
+    name: "CodeNodeExecutionError",
+    exitCode: 1,
+    stderr: expect.stringContaining("text is required"),
+  });
+});
+```
+
+Pass test-only secret values through the bound `run(inputs, { env })`; authored static environment entries are applied automatically. Use `pythonExecutable` only when the project intentionally tests another Python binary, and lower `timeoutMs` for timeout behavior.
+
+## Complete pipeline flow
+
+Start with the first row from the same local dataset file intended for upload. Keep that row as a TypeScript fixture; if it contains sensitive values, redact the values while preserving the real field names, nesting, optionality, and media/value shapes. Use synthetic input only when no local row exists.
+
+```ts
+import { expect, test } from "@toloka-platform/sdk/testing";
+import pipeline from "../pipeline";
+import { representativeTicket } from "./fixtures/support-ticket";
+import { normalizeTicket } from "../nodes/normalize-ticket/node";
+import { classifyTicket } from "../nodes/classify-ticket/node";
+import { finalizeTicket } from "../nodes/finalize-ticket/node";
+
+test.pipeline(
+  pipeline,
+  "moves a representative item from root.started to root.completed",
+  async ({ runCode, renderUi }) => {
+    let item: Record<string, unknown> = { ...representativeTicket };
+
+    item = { ...item, ...(await runCode(normalizeTicket, item)) };
+
+    const classificationTask = await renderUi(classifyTicket, { data: item });
+    await classificationTask.setValue("category", "billing");
+    await classificationTask.setValue("rationale", "The customer disputes a duplicate charge.");
+    const classification = await classificationTask.submit();
+    item = {
+      ...item,
+      category: classification.category,
+      rationale: classification.rationale,
+    };
+
+    item = { ...item, ...(await runCode(finalizeTicket, item)) };
+
+    expect(item).toMatchObject({
+      ticket_id: representativeTicket.ticket_id,
+      category: "billing",
+      resolution_status: "ready",
+    });
+  },
+);
+```
+
+This explicit item-state threading is the local equivalent of following pipeline connections: pass root input to the first node, merge its output, and continue until the completed fields are available. Keep this happy path in one test when the graph is linear. Use separate tests for each match branch or materially different path. For quorum, collect several simulated Task UI submissions and assemble each outer annotation array before calling a downstream code node.
+
+## Default Task UI fixture
+
+```ts
+import { expect, test } from "@toloka-platform/sdk/testing";
+import pipeline from "../../pipeline";
+import { annotate } from "./node";
+
+test.ui(pipeline, annotate, "submits a valid answer", async ({ render }) => {
+  const task = await render({
+    data: { prompt: "What is two plus two?" },
+  });
+
+  await task.setValue("raw_answer", "four");
+
+  expect(await task.validationErrors()).toEqual([]);
+  expect(await task.submit()).toMatchObject({ answer: "four" });
+});
+```
+
+The browser is created once per Vitest worker. The typed wrapper's `render` helper creates an isolated browser context and page for the scenario. Every opened Task UI session is closed automatically after the scenario, including failed scenarios.
+
+## Several TypeScript scenarios
+
+Scenarios are ordinary TypeScript. Use shared builders and loops instead of generating a separate JSON scenario format.
+
+```ts
+import { expect, test } from "@toloka-platform/sdk/testing";
+import pipeline from "../../pipeline";
+import { classify } from "./node";
+
+const scenarios = [
+  { name: "short text", data: { text: "yes" } },
+  { name: "long text", data: { text: "a long paragraph" } },
+  { name: "empty optional context", data: { text: "yes", context: null } },
+];
+
+for (const scenario of scenarios) {
+  test.ui(pipeline, classify, scenario.name, async ({ render }) => {
+    const task = await render({ data: scenario.data });
+
+    await task.setValue("label", "accepted");
+
+    expect(await task.validationErrors()).toEqual([]);
+    expect(await task.submit()).toMatchObject({ label: "accepted" });
+  });
+}
+```
+
+Each scenario receives a fresh browser context, so values set by one scenario cannot satisfy another scenario.
+
+## Inspect component contracts
+
+Component documentation comes from the same TBX launcher used to render the interface.
+
+```ts
+import { expect, test } from "@toloka-platform/sdk/testing";
+import pipeline from "../../pipeline";
+import { classify } from "./node";
+
+test("uses the expected Field contract", async ({ ui }) => {
+  const task = await ui.render(pipeline, classify);
+  const documentation = await task.componentDocumentation(["Field.RadioGroup", "View.Card"]);
+
+  expect(documentation).toMatchObject({
+    "Field.RadioGroup": { valueType: expect.stringContaining("string") },
+    "View.Card": { propsType: expect.stringContaining("title") },
+  });
+});
+```
+
+Requesting an unknown component rejects with an actionable error. It does not silently return an empty entry.
+
+```ts
+await expect(task.componentDocumentation(["Field.Invented"])).rejects.toThrow(
+  "Unknown Task UI components: Field.Invented",
+);
+```
+
+## Assert browser validation failures
+
+```ts
+import { expect, TaskUiValidationError, test } from "@toloka-platform/sdk/testing";
+import pipeline from "../../pipeline";
+import { annotate } from "./node";
+
+test("requires an answer", async ({ ui }) => {
+  const task = await ui.render(pipeline, annotate);
+
+  expect(await task.validationErrors()).toEqual([expect.objectContaining({ path: "raw_answer" })]);
+
+  await expect(task.submit()).rejects.toBeInstanceOf(TaskUiValidationError);
+});
+```
+
+`TaskUiValidationError` exposes three structured fields:
+
+- `formErrors` contains browser component validation failures.
+- `entityErrors` contains postprocessed output values that fail entity schemas.
+- `coverage` reports untested hardware-backed fields.
+
+## Assert postprocessed output
+
+`submit()` returns the final Task UI output after postprocess runs. Launcher-only `_context` metadata is removed.
+
+```ts
+const task = await ui.render(pipeline, normalizeBox);
+
+await task.setValue("raw_box", {
+  x: 20,
+  y: 10,
+  width: 100,
+  height: 50,
+});
+
+expect(await task.submit()).toEqual({
+  raw_box: { x: 20, y: 10, width: 100, height: 50 },
+  box: { x: 0.2, y: 0.1, width: 1, height: 0.5 },
+});
+```
+
+The submitted result is also checked against every non-hardware output entity schema declared by the authored node.
+
+## Hardware-backed fields
+
+Headless Chromium cannot complete native file pickers, cameras, microphones, or recording components. By default, `submit()` rejects rather than claiming complete coverage.
+
+```ts
+const task = await ui.render(pipeline, recordVideo);
+
+expect(task.coverage.complete).toBe(false);
+expect(task.coverage.untestedHardwareFields).toContain("video");
+await expect(task.submit()).rejects.toThrow("hardware-backed fields");
+```
+
+When the scenario deliberately verifies only the testable fields, acknowledge partial coverage explicitly:
+
+```ts
+const task = await ui.render(pipeline, recordVideo, {
+  allowPartialCoverage: true,
+});
+
+await task.setValue("description", "A short outdoor video");
+expect(await task.submit()).toMatchObject({
+  description: "A short outdoor video",
+});
+expect(task.coverage.complete).toBe(false);
+```
+
+A partial scenario is useful for structure and supporting fields, but it is not full verification of the hardware workflow.
+
+## Manual cleanup
+
+Automatic teardown is sufficient for normal tests. Call `close()` only when a long scenario no longer needs a page and should release it early.
+
+```ts
+const task = await ui.render(pipeline, annotate);
+
+await task.screenshot("test-results/initial.png");
+await task.close();
+```
+
+`close()` is idempotent. The fixture’s automatic teardown can safely call it again.
+
+## Setup and execution
+
+```sh
+bun add --dev vitest playwright
+bunx playwright install chromium
+toloka check
+```
+
+The local browser still downloads the hosted launcher, so use synthetic or redacted test data. `toloka check` runs project types, automatic Task UI types, typed node tests, and pipeline-flow evidence. Remote Node Checks remain separate platform jobs.