{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://ondaclip.com/docs/tutorial.schema.json", "title": ".ondaclip/tutorials/.yaml", "description": "One video tutorial. Docs: https://ondaclip.com/docs/tutorial-format/ and https://ondaclip.com/docs/actions/", "type": "object", "additionalProperties": false, "required": [ "id", "title", "steps" ], "properties": { "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$", "description": "Equal to the file name" }, "account": { "type": "string", "description": "The role of the demo account that signs in (not needed when the app has no sign-in)" }, "title": { "description": "The title, in every language", "oneOf": [ { "type": "string" }, { "type": "object", "propertyNames": { "pattern": "^[a-z]{2}-[A-Z]{2}$" }, "additionalProperties": { "type": "string" } } ] }, "voice": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "description": "A Gemini voice (Charon, Kore, Puck…)" }, "style": { "description": "A style prompt for the voice", "oneOf": [ { "type": "string" }, { "type": "object", "propertyNames": { "pattern": "^[a-z]{2}-[A-Z]{2}$" }, "additionalProperties": { "type": "string" } } ] } } }, "clock": { "type": "string", "description": "The time the app shows: \"09:30\" (default) or \"real\"" }, "locales": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "The languages of this tutorial, a part of the product's (since v0.74.0): a new feature in one language first. Default: every language of the product" }, "hide": { "description": "Elements blurred on every screen", "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "testid": { "type": "string" }, "css": { "type": "string" } } } }, "before": { "type": "object", "description": "Set before the app code runs, for example localStorage: { theme: dark }" }, "writes": { "type": "array", "items": { "type": "string" }, "description": "API paths the tutorial may write to (regular expressions); without it the tutorial is read-only. A tutorial that writes needs a cleanup, unless config.yaml says how the team resets its demo data (demoData.reset)" }, "frozenResponses": { "type": "object", "additionalProperties": false, "required": [ "url" ], "properties": { "url": { "type": "string" }, "delay": { "type": "number" } }, "description": "AI or external responses recorded once, then replayed" }, "microphone": { "type": "object", "additionalProperties": false, "required": [ "say" ], "properties": { "say": { "description": "What the browser hears as its microphone", "oneOf": [ { "type": "string" }, { "type": "object", "propertyNames": { "pattern": "^[a-z]{2}-[A-Z]{2}$" }, "additionalProperties": { "type": "string" } } ] }, "voice": { "type": "string" }, "style": { "description": "A style prompt for the microphone voice (since v0.50.0)", "oneOf": [ { "type": "string" }, { "type": "object", "propertyNames": { "pattern": "^[a-z]{2}-[A-Z]{2}$" }, "additionalProperties": { "type": "string" } } ] } } }, "replace": { "type": "object", "additionalProperties": false, "required": [ "file" ], "description": "Fictitious identities in the page: a JSON list of { email, name, initials, fake: { email, name, initials } } written by a setup run in the output of the tutorial, never in the repository; a real one still visible stops the shoot (since v0.50.0)", "properties": { "file": { "type": "string" } } }, "neverShow": { "type": "array", "items": { "type": "string" }, "description": "Texts this tutorial must never show (with the neverShow of config.yaml): one visible and not hidden stops the shoot (since v0.50.0)" }, "singleShoot": { "type": "boolean", "description": "Keep the captures between renders (tutorials that write)" }, "setup": { "type": "array", "items": { "type": "object", "additionalProperties": false, "description": "An action before the first step (setup) or after the last (cleanup), not filmed", "properties": { "attach": { "type": "object", "additionalProperties": false, "required": [ "target" ], "anyOf": [ { "required": [ "file" ] }, { "required": [ "files" ] } ], "description": "Chooses a file (or several: files) of .ondaclip/fixtures/", "properties": { "target": { "description": "One element of the screen: id (best: its data-ondaclip-id, or data-testid), role and name, a visible text, or css (last resort)", "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "The data-ondaclip-id of the element; its data-testid (or the testIdAttribute of the product) is read too" }, "testid": { "type": "string", "description": "Same as id (the name before v0.62.0, still read)" }, "contains": { "type": "string", "description": "With id: the element with this text" }, "role": { "type": "string", "description": "An accessible role (button, link, textbox…)" }, "name": { "type": "string", "description": "With role: its accessible name" }, "text": { "type": "string", "description": "A visible text, exactly" }, "css": { "type": "string", "description": "A CSS selector, the last resort" } }, "anyOf": [ { "required": [ "id" ] }, { "required": [ "testid" ] }, { "required": [ "role" ] }, { "required": [ "text" ] }, { "required": [ "css" ] } ] }, "file": { "type": "string" }, "files": { "type": "array", "minItems": 1, "items": { "type": "string" } } } }, "goto": { "type": "string", "description": "A path of the app" }, "run": { "type": "string", "pattern": "^node \\S", "description": "A command of the repository, off screen: node, a file of the repository and plain arguments, no shell characters; runs from the repository root, 120 s at most (since v0.50.0)" }, "click": { "description": "The cursor clicks. count: 3 for a triple click (a paragraph is selected), button: right for the context menu (since v0.50.0)", "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "The data-ondaclip-id of the element; its data-testid (or the testIdAttribute of the product) is read too" }, "testid": { "type": "string", "description": "Same as id (the name before v0.62.0, still read)" }, "contains": { "type": "string", "description": "With id: the element with this text" }, "role": { "type": "string", "description": "An accessible role (button, link, textbox…)" }, "name": { "type": "string", "description": "With role: its accessible name" }, "text": { "type": "string", "description": "A visible text, exactly" }, "css": { "type": "string", "description": "A CSS selector, the last resort" }, "target": { "description": "One element of the screen: id (best: its data-ondaclip-id, or data-testid), role and name, a visible text, or css (last resort)", "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "The data-ondaclip-id of the element; its data-testid (or the testIdAttribute of the product) is read too" }, "testid": { "type": "string", "description": "Same as id (the name before v0.62.0, still read)" }, "contains": { "type": "string", "description": "With id: the element with this text" }, "role": { "type": "string", "description": "An accessible role (button, link, textbox…)" }, "name": { "type": "string", "description": "With role: its accessible name" }, "text": { "type": "string", "description": "A visible text, exactly" }, "css": { "type": "string", "description": "A CSS selector, the last resort" } }, "anyOf": [ { "required": [ "id" ] }, { "required": [ "testid" ] }, { "required": [ "role" ] }, { "required": [ "text" ] }, { "required": [ "css" ] } ] }, "count": { "enum": [ 1, 2, 3 ] }, "button": { "enum": [ "left", "right", "middle" ] } }, "anyOf": [ { "required": [ "id" ] }, { "required": [ "testid" ] }, { "required": [ "role" ] }, { "required": [ "text" ] }, { "required": [ "css" ] }, { "required": [ "target" ] } ] }, "type": { "type": "object", "additionalProperties": false, "required": [ "target", "text" ], "description": "The typing is filmed", "properties": { "target": { "description": "One element of the screen: id (best: its data-ondaclip-id, or data-testid), role and name, a visible text, or css (last resort)", "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "The data-ondaclip-id of the element; its data-testid (or the testIdAttribute of the product) is read too" }, "testid": { "type": "string", "description": "Same as id (the name before v0.62.0, still read)" }, "contains": { "type": "string", "description": "With id: the element with this text" }, "role": { "type": "string", "description": "An accessible role (button, link, textbox…)" }, "name": { "type": "string", "description": "With role: its accessible name" }, "text": { "type": "string", "description": "A visible text, exactly" }, "css": { "type": "string", "description": "A CSS selector, the last resort" } }, "anyOf": [ { "required": [ "id" ] }, { "required": [ "testid" ] }, { "required": [ "role" ] }, { "required": [ "text" ] }, { "required": [ "css" ] } ] }, "text": { "type": "string" }, "clear": { "type": "boolean" } } }, "select": { "type": "object", "additionalProperties": false, "required": [ "target", "option" ], "description": "An option of a , by value or label", "properties": { "target": { "description": "One element of the screen: id (best: its data-ondaclip-id, or data-testid), role and name, a visible text, or css (last resort)", "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "The data-ondaclip-id of the element; its data-testid (or the testIdAttribute of the product) is read too" }, "testid": { "type": "string", "description": "Same as id (the name before v0.62.0, still read)" }, "contains": { "type": "string", "description": "With id: the element with this text" }, "role": { "type": "string", "description": "An accessible role (button, link, textbox…)" }, "name": { "type": "string", "description": "With role: its accessible name" }, "text": { "type": "string", "description": "A visible text, exactly" }, "css": { "type": "string", "description": "A CSS selector, the last resort" } }, "anyOf": [ { "required": [ "id" ] }, { "required": [ "testid" ] }, { "required": [ "role" ] }, { "required": [ "text" ] }, { "required": [ "css" ] } ] }, "option": { "type": "string" } } }, "wait": { "type": "object", "additionalProperties": false, "description": "Waits for a page, a text, an element or a time", "properties": { "url": { "type": "string" }, "text": { "type": "string" }, "target": { "description": "One element of the screen: id (best: its data-ondaclip-id, or data-testid), role and name, a visible text, or css (last resort)", "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "The data-ondaclip-id of the element; its data-testid (or the testIdAttribute of the product) is read too" }, "testid": { "type": "string", "description": "Same as id (the name before v0.62.0, still read)" }, "contains": { "type": "string", "description": "With id: the element with this text" }, "role": { "type": "string", "description": "An accessible role (button, link, textbox…)" }, "name": { "type": "string", "description": "With role: its accessible name" }, "text": { "type": "string", "description": "A visible text, exactly" }, "css": { "type": "string", "description": "A CSS selector, the last resort" } }, "anyOf": [ { "required": [ "id" ] }, { "required": [ "testid" ] }, { "required": [ "role" ] }, { "required": [ "text" ] }, { "required": [ "css" ] } ] }, "ms": { "type": "number" }, "timeout": { "type": "number" } } }, "check": { "oneOf": [ { "type": "object", "additionalProperties": false, "description": "Checks a text (contains) or the value of a field (value): a tutorial is also an end-to-end test", "required": [ "target" ], "properties": { "target": { "description": "One element of the screen: id (best: its data-ondaclip-id, or data-testid), role and name, a visible text, or css (last resort)", "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "The data-ondaclip-id of the element; its data-testid (or the testIdAttribute of the product) is read too" }, "testid": { "type": "string", "description": "Same as id (the name before v0.62.0, still read)" }, "contains": { "type": "string", "description": "With id: the element with this text" }, "role": { "type": "string", "description": "An accessible role (button, link, textbox…)" }, "name": { "type": "string", "description": "With role: its accessible name" }, "text": { "type": "string", "description": "A visible text, exactly" }, "css": { "type": "string", "description": "A CSS selector, the last resort" } }, "anyOf": [ { "required": [ "id" ] }, { "required": [ "testid" ] }, { "required": [ "role" ] }, { "required": [ "text" ] }, { "required": [ "css" ] } ] }, "contains": { "type": "string" }, "value": {} } }, { "type": "array", "items": { "type": "object", "additionalProperties": false, "description": "Checks a text (contains) or the value of a field (value): a tutorial is also an end-to-end test", "required": [ "target" ], "properties": { "target": { "description": "One element of the screen: id (best: its data-ondaclip-id, or data-testid), role and name, a visible text, or css (last resort)", "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "The data-ondaclip-id of the element; its data-testid (or the testIdAttribute of the product) is read too" }, "testid": { "type": "string", "description": "Same as id (the name before v0.62.0, still read)" }, "contains": { "type": "string", "description": "With id: the element with this text" }, "role": { "type": "string", "description": "An accessible role (button, link, textbox…)" }, "name": { "type": "string", "description": "With role: its accessible name" }, "text": { "type": "string", "description": "A visible text, exactly" }, "css": { "type": "string", "description": "A CSS selector, the last resort" } }, "anyOf": [ { "required": [ "id" ] }, { "required": [ "testid" ] }, { "required": [ "role" ] }, { "required": [ "text" ] }, { "required": [ "css" ] } ] }, "contains": { "type": "string" }, "value": {} } } } ] }, "remember": { "oneOf": [ { "type": "object", "additionalProperties": false, "description": "Keeps a text of the screen (target, pattern, attribute) or a part of the address (url); {name} uses it later", "required": [ "name" ], "properties": { "name": { "type": "string" }, "target": { "description": "One element of the screen: id (best: its data-ondaclip-id, or data-testid), role and name, a visible text, or css (last resort)", "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "The data-ondaclip-id of the element; its data-testid (or the testIdAttribute of the product) is read too" }, "testid": { "type": "string", "description": "Same as id (the name before v0.62.0, still read)" }, "contains": { "type": "string", "description": "With id: the element with this text" }, "role": { "type": "string", "description": "An accessible role (button, link, textbox…)" }, "name": { "type": "string", "description": "With role: its accessible name" }, "text": { "type": "string", "description": "A visible text, exactly" }, "css": { "type": "string", "description": "A CSS selector, the last resort" } }, "anyOf": [ { "required": [ "id" ] }, { "required": [ "testid" ] }, { "required": [ "role" ] }, { "required": [ "text" ] }, { "required": [ "css" ] } ] }, "pattern": { "type": "string" }, "attribute": { "type": "string" }, "url": { "type": "string" } } }, { "type": "array", "items": { "type": "object", "additionalProperties": false, "description": "Keeps a text of the screen (target, pattern, attribute) or a part of the address (url); {name} uses it later", "required": [ "name" ], "properties": { "name": { "type": "string" }, "target": { "description": "One element of the screen: id (best: its data-ondaclip-id, or data-testid), role and name, a visible text, or css (last resort)", "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "The data-ondaclip-id of the element; its data-testid (or the testIdAttribute of the product) is read too" }, "testid": { "type": "string", "description": "Same as id (the name before v0.62.0, still read)" }, "contains": { "type": "string", "description": "With id: the element with this text" }, "role": { "type": "string", "description": "An accessible role (button, link, textbox…)" }, "name": { "type": "string", "description": "With role: its accessible name" }, "text": { "type": "string", "description": "A visible text, exactly" }, "css": { "type": "string", "description": "A CSS selector, the last resort" } }, "anyOf": [ { "required": [ "id" ] }, { "required": [ "testid" ] }, { "required": [ "role" ] }, { "required": [ "text" ] }, { "required": [ "css" ] } ] }, "pattern": { "type": "string" }, "attribute": { "type": "string" }, "url": { "type": "string" } } } } ] }, "ifPresent": { "oneOf": [ { "type": "boolean" }, { "type": "integer", "minimum": 0, "maximum": 30000 } ], "description": "Skip it when its target or remembered value is not there; a number: wait that many ms for the target first (since v0.67.0)" }, "key": { "type": "string", "pattern": "^[A-Za-z0-9+]+$", "description": "A key pressed (off screen in an action, before the action in a shot), for example Escape to close an open menu (since v0.52.0)" } } }, "description": "Always runs, even after a failure: undo what the tutorial wrote" }, "steps": { "type": "array", "minItems": 1, "description": "The chapters of the video", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "title", "shots" ], "properties": { "id": { "type": "string" }, "title": { "description": "The title of the step", "oneOf": [ { "type": "string" }, { "type": "object", "propertyNames": { "pattern": "^[a-z]{2}-[A-Z]{2}$" }, "additionalProperties": { "type": "string" } } ] }, "start": { "type": "string", "description": "The path the step opens" }, "hide": { "description": "Elements blurred on every screen", "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "testid": { "type": "string" }, "css": { "type": "string" } } } }, "voice": { "type": "object" }, "mock": { "type": "array", "description": "While the step plays, GET requests matching url get this JSON (since v0.50.0)", "items": { "type": "object", "additionalProperties": false, "required": [ "url", "json" ], "properties": { "url": { "type": "string", "description": "A regular expression of the request URL" }, "json": { "description": "The answer" } } } }, "shots": { "type": "array", "minItems": 1, "items": { "type": "object", "additionalProperties": false, "required": [ "say" ], "description": "One sentence and at most one action (show, click, type, select, scroll, hover, hold, attach)", "properties": { "say": { "description": "The sentence of the voice; it sets the length of the shot", "oneOf": [ { "type": "string" }, { "type": "object", "propertyNames": { "pattern": "^[a-z]{2}-[A-Z]{2}$" }, "additionalProperties": { "type": "string" } } ] }, "show": { "description": "The camera zooms on the target, the cursor moves to it, a ring appears", "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "The data-ondaclip-id of the element; its data-testid (or the testIdAttribute of the product) is read too" }, "testid": { "type": "string", "description": "Same as id (the name before v0.62.0, still read)" }, "contains": { "type": "string", "description": "With id: the element with this text" }, "role": { "type": "string", "description": "An accessible role (button, link, textbox…)" }, "name": { "type": "string", "description": "With role: its accessible name" }, "text": { "type": "string", "description": "A visible text, exactly" }, "css": { "type": "string", "description": "A CSS selector, the last resort" } }, "anyOf": [ { "required": [ "id" ] }, { "required": [ "testid" ] }, { "required": [ "role" ] }, { "required": [ "text" ] }, { "required": [ "css" ] } ] }, "click": { "description": "The cursor clicks. count: 3 for a triple click (a paragraph is selected), button: right for the context menu (since v0.50.0)", "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "The data-ondaclip-id of the element; its data-testid (or the testIdAttribute of the product) is read too" }, "testid": { "type": "string", "description": "Same as id (the name before v0.62.0, still read)" }, "contains": { "type": "string", "description": "With id: the element with this text" }, "role": { "type": "string", "description": "An accessible role (button, link, textbox…)" }, "name": { "type": "string", "description": "With role: its accessible name" }, "text": { "type": "string", "description": "A visible text, exactly" }, "css": { "type": "string", "description": "A CSS selector, the last resort" }, "target": { "description": "One element of the screen: id (best: its data-ondaclip-id, or data-testid), role and name, a visible text, or css (last resort)", "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "The data-ondaclip-id of the element; its data-testid (or the testIdAttribute of the product) is read too" }, "testid": { "type": "string", "description": "Same as id (the name before v0.62.0, still read)" }, "contains": { "type": "string", "description": "With id: the element with this text" }, "role": { "type": "string", "description": "An accessible role (button, link, textbox…)" }, "name": { "type": "string", "description": "With role: its accessible name" }, "text": { "type": "string", "description": "A visible text, exactly" }, "css": { "type": "string", "description": "A CSS selector, the last resort" } }, "anyOf": [ { "required": [ "id" ] }, { "required": [ "testid" ] }, { "required": [ "role" ] }, { "required": [ "text" ] }, { "required": [ "css" ] } ] }, "count": { "enum": [ 1, 2, 3 ] }, "button": { "enum": [ "left", "right", "middle" ] } }, "anyOf": [ { "required": [ "id" ] }, { "required": [ "testid" ] }, { "required": [ "role" ] }, { "required": [ "text" ] }, { "required": [ "css" ] }, { "required": [ "target" ] } ] }, "type": { "type": "object", "additionalProperties": false, "required": [ "target", "text" ], "description": "The typing is filmed", "properties": { "target": { "description": "One element of the screen: id (best: its data-ondaclip-id, or data-testid), role and name, a visible text, or css (last resort)", "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "The data-ondaclip-id of the element; its data-testid (or the testIdAttribute of the product) is read too" }, "testid": { "type": "string", "description": "Same as id (the name before v0.62.0, still read)" }, "contains": { "type": "string", "description": "With id: the element with this text" }, "role": { "type": "string", "description": "An accessible role (button, link, textbox…)" }, "name": { "type": "string", "description": "With role: its accessible name" }, "text": { "type": "string", "description": "A visible text, exactly" }, "css": { "type": "string", "description": "A CSS selector, the last resort" } }, "anyOf": [ { "required": [ "id" ] }, { "required": [ "testid" ] }, { "required": [ "role" ] }, { "required": [ "text" ] }, { "required": [ "css" ] } ] }, "text": { "type": "string" }, "clear": { "type": "boolean" } } }, "select": { "type": "object", "additionalProperties": false, "required": [ "target", "option" ], "description": "An option of a