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

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

@@ -1 +1 @@
-2e4e22afc766a0a267262fe07718505b43f1cdf364e402a990279e224ad92923  toloka.js.jsc
+30967b83b7ae6c50962e2482725ca2fb43f1526f3f16b9af2ef2bbe29fd00b7c  toloka.js.jsc

package/dist/cli/toloka.js.sha256

@@ -1 +1 @@
-842c3cdfb47d5a899375c288cefa8ba550c22301dbd47d99d224a8b34acd01a2  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>]
@@ -282,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
@@ -311,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/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.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
 

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.

package/docs/testing.md

@@ -0,0 +1,115 @@
+# Test pipelines locally
+
+The `@toloka-platform/sdk/testing` entry point provides typed Vitest wrappers for executable Python `code` nodes, Chromium Task UI scenarios, and complete pipeline flows. `toloka check` runs those tests together with project TypeScript and automatic Task UI typechecking without creating or modifying a platform project.
+
+## Install test dependencies
+
+```sh
+bun add --dev vitest playwright
+bunx playwright install chromium
+```
+
+Code-node tests also require `python3` on the test machine. See [testing examples](./testing-examples.md) for parameterization, validation failures, hardware coverage, and cleanup patterns.
+
+## Test a code node
+
+`test.code(pipeline, node, name, callback)` binds one test to one authored code node. Its `run(inputs, options?)` helper executes the Python source with the same async `main(inputs)` entry contract. The test counts as node coverage only after `run` executes, at least one assertion runs, and the callback passes.
+
+```ts
+import { expect, test } from "@toloka-platform/sdk/testing";
+import pipeline from "../../pipeline";
+import { normalize } from "./node";
+
+test.code(pipeline, normalize, "normalizes whitespace", async ({ run }) => {
+  await expect(run({ text: "  hello  " })).resolves.toEqual({
+    normalized_text: "hello",
+  });
+});
+```
+
+Failures from the bound executor throw `CodeNodeExecutionError` with the Python exit code and stderr. Authored static environment values are included; pass secret or test-specific values through the optional `run` options. Third-party imports must be available to the selected Python executable.
+
+`test.code` defaults to 30 seconds, which exceeds the code runner's 10-second default. Pass `{ timeout: milliseconds }` after the callback when the scenario also raises the runner timeout.
+
+## Test a complete pipeline flow
+
+Register the representative connected scenario with `test.pipeline(pipeline, name, callback)`. Its callback provides `runCode(node, inputs, options?)` and `renderUi(node, options?)` bound to that pipeline.
+
+Use the first row from the same local dataset file intended for upload when one is available. If it contains sensitive values, keep a redacted fixture that preserves field names, nesting, optionality, and media/value shapes. Use synthetic input only when no local row exists. `test.pipeline` does not fetch a live dataset: the local gate remains deterministic, credential-free, and usable before apply. Treat the fixture as `root.started` item state, execute connected nodes in order, merge only each node's declared outputs, and assert the fields accepted by `root.completed`. A linear happy path can stay in one test; use separate scenarios for materially different match branches, optional paths, and failures.
+
+## Test a Task UI
+
+Create a file ending in `.ui.spec.ts` next to the human-work node. `test.ui` binds the test to the pipeline and node, and its callback receives `render(options?)` for that target. The test counts as coverage only after a successful submission, at least one assertion, and a passing callback.
+
+Browser-backed `test.ui` scenarios default to 60 seconds, which exceeds the launcher's 45-second setup budget. `test.pipeline` scenarios default to 120 seconds for connected flows with multiple UI steps. Pass `{ timeout: milliseconds }` after the callback to tune either wrapper without weakening its inner launcher deadlines.
+
+```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",
+  });
+  await task.screenshot("test-results/answer.png");
+});
+```
+
+Run the complete gate rather than invoking Vitest separately:
+
+```sh
+toloka check
+```
+
+Use an ordinary TypeScript loop to register several `test.code` or `test.ui` scenarios. There is no separate JSON scenario format.
+
+## Fixture API
+
+The low-level `ui` fixture remains available inside ordinary Vitest tests for component discovery and exploratory work, but plain tests do not satisfy required node coverage. Use typed wrappers for committed gate evidence. Importing `@toloka-platform/sdk/testing` from a plain Bun script executes Vitest fixture setup and fails.
+
+- `ui.componentDocumentation(names?)` returns the current launcher's supported component contracts. Call it before choosing component names or props.
+- `ui.render(pipeline, node, options)` creates a fresh browser context and returns a Task UI session for exactly that authored node. `test.ui` supplies the equivalent bound `render(options?)` helper.
+
+The returned Task UI session supports:
+
+- `componentTree()` returns the rendered component hierarchy.
+- `componentDocumentation(names?)` returns component props, value shapes, capabilities, and limitations.
+- `setValue(path, value)` and `getValue(path)` address Fields by their stable `path`, not generated component ids.
+- `validationErrors()` returns browser-level required-field and component-rule failures with Field paths.
+- `submit()` executes preprocess/postprocess, removes the launcher's `_context`, and validates declared output entities. The returned form data can also contain echoed inputs; assert output-entity keys and values without treating those inputs as output entities.
+- `screenshot(path)` writes a full-page PNG to the local filesystem.
+- `coverage` states whether hardware-backed fields were exercised completely.
+
+One Chromium process is shared per Vitest worker. Every scenario gets a fresh context and page and is cleaned up automatically.
+
+For a structured or array-valued Field, derive the dataset field schema from the component's documented `valueType`. In its typed UI scenario, adapt only semantic values such as labels, then pass the documented example value through `setValue`, `getValue`, and `submit`. This catches component-shape drift before a postprocess can read absent keys and silently write fallback data.
+
+## Runtime rules
+
+`ui.code` must parse as one JSX root. Every identifier must be a component returned by `componentDocumentation()` or a documented `actions` API. `toloka check` applies full TypeScript semantic checking with declarations bundled in the SDK; the real launcher then renders the same JSX in browser scenarios. Treat a component's `propsType` and `example` together as its contract.
+
+`preprocess` and `postprocess` are JavaScript function bodies, not TypeScript:
+
+Valid JavaScript: `items.map((item) => item.value)`
+
+Invalid runtime JavaScript: `items.map((item: unknown) => item.value)`
+
+`preprocess` can run again after form state changes. Use it to shape input data; if it prefills a bound field, return that key only while it is absent so later edits are not overwritten. A `Field`-bound top-level key already enters the submission. `postprocess` must return only new top-level keys: bind a component to a draft key when postprocess must derive a different entity key.
+
+The fixture loads the hosted TBX launcher in a fresh local Chromium context, so tests require network access but do not use Azure Playwright or Potato application services. The context has no platform cookies or credentials. Use synthetic or redacted fixtures because the hosted launcher executes with access to the supplied test data.
+
+## Hardware-backed fields
+
+File pickers, video upload/recording, and other hardware-backed fields cannot be completed reliably in headless Chromium. `task.coverage.complete` is `false` when these components are present. Render with `allowPartialCoverage: true`, inject one value matching the component's documented `valueType` through `setValue`, and assert the postprocessed output shape yourself: entity validation skips hardware-backed paths, and `getValue` may not serialize their launcher state. This checks browser validation and mapping only, not capture, upload, link generation, or record-time constraints. A partial result must not be described as complete coverage.
+
+## Final gate
+
+`toloka check` loads every authored pipeline, runs the project TypeScript compiler, typechecks every Task UI against declarations bundled with the installed SDK, runs Vitest, and requires passing `test.code`, `test.ui`, and `test.pipeline` evidence. `missing`, `failed`, `partial`, and `infrastructure_error` are distinct blocking outcomes. `toloka apply` reruns this complete gate before resolving credentials or writing platform state. Platform source/spec errors from `toloka validate` remain separate; `not_ran_node_check` describes a Remote Node Check and does not replace local evidence.