@toloka-platform/sdk 0.1.0-preview.5 → 0.1.0-preview.7

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

@@ -1 +1 @@
-bbe06fffb8a659ebc2903d962ff2b4a225fe3abc691e607a01258350163c36c7  toloka.js.jsc
+30967b83b7ae6c50962e2482725ca2fb43f1526f3f16b9af2ef2bbe29fd00b7c  toloka.js.jsc

package/dist/cli/toloka.js.sha256

@@ -1 +1 @@
-43e152b2ae5342013785dd1c89843bead8b68039ea6576ae5a8bea5944263127  toloka.js
+939f5c749f0a627df3f3f0b042e9ef0fffa4c2ccc77f61f20c52ae77b767b20b  toloka.js

package/docs/authoring.md

@@ -77,6 +77,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 +134,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 +148,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 {};",
@@ -258,7 +271,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
 
@@ -65,7 +64,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
@@ -152,15 +151,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 +200,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>]
@@ -202,6 +215,31 @@ toloka pipeline results <runId> [--limit <n>] [--failed]
 
 `pipeline status` reports the latest run of that pipeline. `pipeline runs` lists recent runs (default 10). `pipeline cost` forecasts what a run would bill. `pipeline cancel` and `pipeline results` take a run id.
 
+## base-model
+
+Inspect the global, read-only Base Model Catalog.
+
+```sh
+toloka base-model list [--json]
+toloka base-model get <id> [--json]
+```
+
+Human-readable output is the default. `base-model list` prints aligned ID, name, provider, and upstream-model columns; `base-model get` prints labeled fields including the pinned revision. Pass `--json` for machine-readable output.
+
+## model
+
+Manage Model metadata in the selected project.
+
+```sh
+toloka model list [--json]
+toloka model get <name-or-id> [--json]
+toloka model versions <name-or-id> [--json]
+toloka model create <name> --base <base-model-id> [--description <text>] [--json]
+toloka model archive <name-or-id> [--json]
+```
+
+`model create` creates project-owned Model metadata linked to one catalog Base Model; it does not create a Model Version. Human-readable output is the default for every command in this group. Pass `--json` for machine-readable objects or arrays. Weight upload, validation, download, and Model Version creation are deferred.
+
 ## dataset
 
 Catalog and row commands for datasets in the selected project. Name or id is accepted; duplicate names must be addressed by id.
@@ -219,7 +257,7 @@ toloka dataset upload <name> <file>
 
 `dataset load` starts a platform export, waits for it (default 60s; pass `--timeout`), downloads the JSON array, and writes JSONL to `--out`. `--limit` slices after download; it still waits for the full export. On timeout the message names the export id. Failed downloads and invalid payloads leave `--out` untouched.
 
-`dataset upload` appends JSONL rows. Field schemas are immutable after the first upload: you can add columns, never alter or remove one. See [datasets](./datasets.md).
+`dataset upload` accepts `.json` arrays, `.jsonl` files with one object per line, and `.csv` files with a header row. The CLI infers the format from the extension and uploads the original bytes without conversion. If the blob transfer or finalization fails, the CLI cancels the started upload before returning the error, so another upload can start immediately and may reuse the same filename. Field schemas are immutable after the first successful upload: you can add columns, never alter or remove one. See [datasets](./datasets.md).
 
 ## report
 
@@ -257,21 +295,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
@@ -286,7 +324,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/datasets.md

@@ -109,17 +109,16 @@ toloka dataset upload face-images data/face_images.jsonl
 
 The command takes two positional arguments and has no flags:
 
-| Argument | Description                          |
-| -------- | ------------------------------------ |
-| `<name>` | Dataset name or id                   |
-| `<file>` | JSONL file, one JSON object per line |
+| Argument | Description                                |
+| -------- | ------------------------------------------ |
+| `<name>` | Dataset name or id                         |
+| `<file>` | `.json`, `.jsonl`, or `.csv` file to append |
 
-Each line is a JSON object with keys matching column names:
+The CLI infers the format from the filename extension and uploads the original bytes without conversion:
 
-```json
-{"image_url": "https://example.com/cat-1.jpg"}
-{"image_url": "https://example.com/cat-2.jpg"}
-```
+- `.json` contains an array of row objects.
+- `.jsonl` contains one row object per non-empty line and is validated locally before upload.
+- `.csv` uses its header row for field names; every value is ingested as a string.
 
 Upload is additive: it appends items and never rewrites existing ones. If the dataset does not exist yet and a pipeline in source declares it, `dataset upload` creates the dataset with the declared columns automatically. If no pipeline declares the dataset, upload stops and asks you to bind a pipeline to it in source so its columns are known, or to upload to an existing dataset. Duplicate live names must be addressed by id.
 

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.5`. 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.7`. 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
 
@@ -39,13 +39,10 @@ A `code` node carries its Python as an inline string in `code.code`. There is no
 
 These are reproduced platform-side issues that affect the SDK path. They are not SDK bugs and cannot be fixed from this package.
 
-| defect                                                                                  | effect on you                                                                                           | workaround                                                        |
-| --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
-| Re-uploading a filename already used in a dataset returns a bodyless `500`              | running the same `toloka dataset upload` twice fails                                                    | use a distinct filename per upload                                |
-| A failed upload leaves a pending upload row, and a pending upload counts as in progress | later uploads to that dataset return `409 Another upload is already in progress`, with no public cancel | load into a new dataset; ask for the pending upload to be cleared |
-| Finalizing a file upload can return a bodyless `500`                                    | `toloka dataset upload` cannot complete on an affected environment                                      | declare columns in source and load rows through a client call     |
-| Rows added through the items endpoint skip column inference                             | `toloka dataset fields` reports no columns for a dataset that holds rows                                | declare columns in source rather than inferring them              |
-| Starting a run intermittently returns a bodyless `500`                                  | `toloka pipeline run` fails with nothing to act on                                                      | check `toloka pipeline runs <name>` for a created run, then retry |
+| defect                                                      | effect on you                                                            | workaround                                                        |
+| ----------------------------------------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------- |
+| Rows added through the items endpoint skip column inference | `toloka dataset fields` reports no columns for a dataset that holds rows | declare columns in source rather than inferring them              |
+| Starting a run intermittently returns a bodyless `500`      | `toloka pipeline run` fails with nothing to act on                       | check `toloka pipeline runs <name>` for a created run, then retry |
 
 ## Not attempted yet
 

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.