Soubor scénáře
Scénář je soubor YAML (obvykle v qa/flows/), který popisuje jedno flow: jeho kroky, šipky mezi nimi a to, co má každý krok splnit. Jeho formát je qawalk.scenario.v1; kaloko validate <soubor> soubor podle něj zkontroluje. Jak scénář napsat krok za krokem: Napsat scénář.
schema: qawalk.scenario.v1
id: WEB-12-checkout
title: Checkout
locales: [en, cs]
viewports: { desktop: [1280, 800], mobile: iphone-15 }
environments: [local, staging]
nodes:
- id: cart
kind: screen
title: { en: Cart, cs: Košík }
path: /cart
purpose: The shopper sees what they are buying and can continue.
execution: { strategy: playwright, script: steps/cart.mjs, instructions: Add one product and open the cart. }
criteria:
- { id: AC1, text: Shows the total, check: { type: deterministic, assert: exists, selector: .cart-total } }
- id: payment
kind: screen
title: Payment
path: /checkout/payment
packs: [a11y]
edges:
- { from: cart, to: payment }
Klíče nejvyšší úrovně
Povinné jsou schema, id, title, nodes a edges.
| Klíč | Co obsahuje |
|---|---|
schema | vždy qawalk.scenario.v1 |
id | id scénáře (malá písmena, číslice, pomlčky); úkol v něm (WEB-12-…) propojí issue |
title | název pro lidi |
kind | task (výchozí) nebo flow |
archived | true skryje vyřazený scénář ze seznamu; jeho běhy zůstanou dostupné |
source | cesta k akceptačnímu plánu (ACCEPTANCE.md), používá ji kaloko validate --coverage |
version | číslo, které zvýšíte, když se flow změní |
locales | jazyky, ve kterých se prochází, např. [en, cs] |
viewports | názvy s velikostí ([1280, 800]), předvolba zařízení (iphone-15, ipad-landscape) nebo seznam předvoleb |
browsers | chromium (výchozí), webkit, firefox |
color_schemes | light, dark |
reduced_motion | no-preference, reduce |
forced_colors | none, active (vysoký kontrast ve Windows) |
display_modes | browser, standalone (nainstalovaná webová aplikace) |
devices | scénáře aplikací: emulátory, simulátory nebo telefony, na kterých se prochází |
token_modes | designová prostředí: které režimy sady tokenů vykreslit ([brand-a, brand-b]), nebo false jen pro default_token_mode prostředí; bez něj všechny režimy |
environments | prostředí z konfigurace, na kterých scénář smí běžet |
readonly | true u scénáře, který jen čte; na prostředí jen pro čtení je povinné |
platform | web (výchozí), android, ios, electron, desktop, windows |
health | acceptance: [seo]: packy, jejichž kontroly se v tomto scénáři počítají do přijetí; bez toho jsou kontroly z packů jen kondice (Kontrola kondice aplikace). site: true (nebo { paths, ai_crawlers, sitemaps, environments }) přidá jednou za běh kontroly celého webu: robots.txt, sitemapy, llms.txt, přesměrování (Kritéria, kontroly a packy). design_packs: [console]: packy jen pro kód (seo, aeo, perf, console, errors), které mají běžet i na designových prostředích, kde jsou jinak vypnuté |
traffic | čísla ze Search Console a GA4 pro stránky tohoto scénáře; nahradí traffic z konfigurace (Konfigurační soubor) |
tags | volné štítky |
refs | odkazy na požadavky, které scénář ověřuje, tak, jak je píše váš tracker nebo QMS ([URS-12, FS-3.4]); v matici dohledatelnosti platí pro každé kritérium (doklady o kvalitě) |
nodes | kroky (níže) |
edges | šipky mezi kroky (níže) |
lanes | popisky řádků na plachtě, index = číslo řádku (odkaz končící #lane=<číslo> otevře daný řádek) |
issue | úkol: number, repo (owner/name), key (Jira nebo Linear, ENG-42), url, title |
sessions | lidé ve flow, každý s title, volitelně mailbox, account, blocked_on |
project | projekt v Kaloku pro jeho běhy; přebije konfiguraci. Když konfigurace chce po každém scénáři vlastní projekt (komentář, nebo produkt s projects:), kaloko validate a kaloko start na chybějící projekt upozorní |
product, module | který produkt a modul z products: flow ukazuje, pro changelog a dokumentaci |
capture | kvalita snímků pro všechny kroky (níže) |
pii | redact nebo pseudonymize: osobní údaje skryté ve všech snímcích, vyhledané automaticky (návod) |
Klíče kroku (nodes)
Každý krok potřebuje id, kind a title.
| Klíč | Co obsahuje |
|---|---|
id | id kroku, používá se v odkazech, v --steps a v odkazech na kroky (kaloko:<scénář>/<krok>) |
kind | screen, email, external (obrazovka třetí strany), decision, stack (mnoho stránek jedné šablony) |
title | text, nebo jeden pro každý jazyk ({ en: Cart, cs: Košík }) |
path | adresa vůči base_url, nebo jedna pro každý jazyk; ve scénářích aplikací deep link; {random} vytvoří adresu, která nemůže existovat |
purpose | jedna věta o tom, k čemu krok slouží; čte ji evaluátor |
refs | odkazy na požadavky u kroku; v matici dohledatelnosti platí pro jeho kritéria |
lane | řádek na plachtě |
readonly | krok jen čte |
execution | strategy (playwright, script, agent, manual), script (cesta ke skriptu kroku), instructions (povinné), requires (např. browser) |
mail | e-mailové kroky: subject a to |
criteria | co má krok splnit (níže) |
session | který člověk ze sessions krok dělá |
affects | masky souborů, které krok ovlivňují, pro kaloko walk --affected, nebo always |
packs | hotové sady kontrol kondice: seo, usability, a11y, perf, console, errors, app, aeo, locale a design, který se počítá do přijetí |
expect_status | stav HTTP, kterým má krok odpovědět, např. 404 (nebo seznam). Stav 400 a vyšší označí chybovou stránku: pack errors kontroluje HC601 (měkká 404) a HC605 (vysvětlení) jen na chybových stránkách, tedy s expect_status nebo při odpovědi 4xx/5xx |
capture | kvalita snímků jen pro tento krok |
record | true nahraje video kroku, i když průchod nenahrává; false nikdy |
ignore | oblasti vynechané z porovnání pixelů: { selector } nebo { rect: [x, y, w, h], viewport }, volitelně omezené přes viewports, locales, s poznámkou note |
items | stack kroky: odkud se berou stránky (urls, file, sitemap (i gzip; sitemap: robots nebo robots: true čte sitemapy z /robots.txt pro procházený jazyk) s match/exclude/limit, crawl, script). match a exclude jsou regulární výraz nebo mapa podle jazyka ({ default: '^/eshop/', fi: '^/fi/tuotteet/' }) a u každého zdroje platí před limit; rotate: week nebo rotate: run vezme limit stránek každý týden nebo běh z jiného místa, takže velký seznam projde po částech; variants: hreflang (se source_locale) vezme seznam v jednom jazyce a v ostatních projde hreflang alternativu každé stránky, takže stránka a její překlady jsou ve stacku jedna stránka a chybějící překlad se nahlásí (HC1005), v kaloko walk i v hostovaných bězích; params dostane script, který dostane i node (id, title, lane, lane_title, session); skript nebo seznam v JSON může každé stránce dát edit_url (stránka v CMS) a content_ref (její záznam) a resolve: steps/resolve.mjs (výchozí export (item, ctx) => ({ edit_url, content_ref })) je doplní procházeným stránkám pro index stacku a kaloko export findings; v designovém prostředí jsou varianty složky kroku, vyjmenované v urls, nebo každá podsložka s index.html |
fields | stack kroky: až 12 sloupců indexu stacku (id, label, from: title, h1, description, canonical, lang, words, http, jsonld_types, meta tag jako og:title nebo meta:robots, CSS selektor, selektor@atribut, count:selektor) |
details | pojmenované části obrazovky pro návody: { id, name, selector }, volitelně context (section, card, page nebo CSS selektor), padding a states; v dokumentaci je ukáže kaloko:<scénář>/<krok>#<id> (Publikovat živou dokumentaci) |
states | další stavy, ve kterých se krok snímá, např. [empty, error, loading]; název může být jakýkoli (níže) |
Kritéria
Každé kritérium má id (AC1, AC12b), text pro lidi, volitelně highlight (CSS selektor, který se na screenshotu orámuje), volitelně refs (identifikátory požadavků, které ověřuje, volný text) a právě jednu kontrolu check: deterministic, semantic nebo manual. Všechny typy kontrol a jejich volby najdete v Kritéria, kontroly a packy.
environments: [production] omezí kritérium na některá prostředí, states: [empty] na některé stavy kroku. Jinde se ukáže jako nepoužitelné a krok kvůli němu nebude částečný.
Stavy kroku
Košík není jedna obrazovka: může být prázdný, nemusí se načíst nebo se ještě načítá. states: u kroku nasnímá každý z těchto stavů vedle výchozího:
- id: cart
kind: screen
title: Košík
path: /cart
states: [empty, error, loading]
execution: { strategy: playwright, script: steps/cart.mjs, instructions: Otevřete košík. }
criteria:
- { id: AC1, text: Ukazuje celkovou cenu, check: { type: deterministic, assert: exists, selector: .cart-total } }
- { id: AC2, text: Říká, že je košík prázdný, states: [empty], check: { type: semantic, question: Říká stránka, že je košík prázdný? } }
- Průchod spustí skript kroku jednou pro každý stav a předá mu ho jako
state(nejdřív'default'). Skript stránku do stavu dostane sám: vyprázdní košík, podvrhne chybu API, zpomalí odpověď. - Designový krok pro stav
emptyvykreslícart/empty.html(pro jazykcart/cs/empty.html). Když stránka chybí, Kaloko otevřecart/index.html?state=empty, takže jedna stránka může stavy přepínat sama. - Každý stav má vlastní screenshoty a verdikty. Na plachtě přibude vedle jazyka přepínač Stav kroku, režim revize i mřížka ukazují vybraný stav a krok, který takový stav nemá, ukáže svou výchozí obrazovku.
Šipky (edges)
| Klíč | Co obsahuje |
|---|---|
from, to | id kroků |
label | text u šipky, třeba volba v rozhodnutí |
kind | main (výchozí), nebo alt pro alternativní cestu |
Snímky (capture)
| Klíč | Co obsahuje |
|---|---|
format | webp (výchozí), nebo png (bezeztrátový, pro tisk) |
scale | 1 nebo 2 (pixely zařízení na snímku) |
quality | kvalita WebP od 0,3 do 1 |
mask | osobní údaje skryté ve všem, co krok uloží: CSS selektory, auto (vyhledávání), nebo obojí; masky scénáře a kroku se sčítají (návod) |
annotate | očíslované značky u prvků kritérií s highlight |
full_page | celá stránka (výchozí, i u stránek stacku), nebo s false jen první obrazovka: u dlouhých stránek několikrát menší |
screenshot | thumb uloží jako obrázek kroku jen malý náhled (640 px na šířku, na výšku jako zachycená stránka): pro stacky se stovkami stránek, kde kontroly čtou stránku, ne obrázek, nejmenší spolu s full_page: false; výchozí full |
record | true, step, flow, failed nebo off; viz kaloko walk --record |
trace | ke každému kroku záznam akcí, požadavků a konzole (výchozí true) |
capture kroku má přednost před scénářem a scénář před konfigurací; výjimkou jsou masky, ty se sčítají.