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
schemavždy qawalk.scenario.v1
idid scénáře (malá písmena, číslice, pomlčky); úkol v něm (WEB-12-…) propojí issue
titlenázev pro lidi
kindtask (výchozí) nebo flow
archivedtrue skryje vyřazený scénář ze seznamu; jeho běhy zůstanou dostupné
sourcecesta k akceptačnímu plánu (ACCEPTANCE.md), používá ji kaloko validate --coverage
versiončíslo, které zvýšíte, když se flow změní
localesjazyky, ve kterých se prochází, např. [en, cs]
viewportsnázvy s velikostí ([1280, 800]), předvolba zařízení (iphone-15, ipad-landscape) nebo seznam předvoleb
browserschromium (výchozí), webkit, firefox
color_schemeslight, dark
reduced_motionno-preference, reduce
forced_colorsnone, active (vysoký kontrast ve Windows)
display_modesbrowser, standalone (nainstalovaná webová aplikace)
devicesscénáře aplikací: emulátory, simulátory nebo telefony, na kterých se prochází
token_modesdesignová 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
environmentsprostředí z konfigurace, na kterých scénář smí běžet
readonlytrue u scénáře, který jen čte; na prostředí jen pro čtení je povinné
platformweb (výchozí), android, ios, electron, desktop, windows
healthacceptance: [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)
tagsvolné štítky
refsodkazy 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ě)
nodeskroky (níže)
edgesšipky mezi kroky (níže)
lanespopisky řá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
sessionslidé ve flow, každý s title, volitelně mailbox, account, blocked_on
projectprojekt 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, modulekterý produkt a modul z products: flow ukazuje, pro changelog a dokumentaci
capturekvalita snímků pro všechny kroky (níže)
piiredact 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
idid kroku, používá se v odkazech, v --steps a v odkazech na kroky (kaloko:<scénář>/<krok>)
kindscreen, email, external (obrazovka třetí strany), decision, stack (mnoho stránek jedné šablony)
titletext, nebo jeden pro každý jazyk ({ en: Cart, cs: Košík })
pathadresa vůči base_url, nebo jedna pro každý jazyk; ve scénářích aplikací deep link; {random} vytvoří adresu, která nemůže existovat
purposejedna věta o tom, k čemu krok slouží; čte ji evaluátor
refsodkazy na požadavky u kroku; v matici dohledatelnosti platí pro jeho kritéria
laneřádek na plachtě
readonlykrok jen čte
executionstrategy (playwright, script, agent, manual), script (cesta ke skriptu kroku), instructions (povinné), requires (např. browser)
maile-mailové kroky: subject a to
criteriaco má krok splnit (níže)
sessionkterý člověk ze sessions krok dělá
affectsmasky souborů, které krok ovlivňují, pro kaloko walk --affected, nebo always
packshotové sady kontrol kondice: seo, usability, a11y, perf, console, errors, app, aeo, locale a design, který se počítá do přijetí
expect_statusstav 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
capturekvalita snímků jen pro tento krok
recordtrue nahraje video kroku, i když průchod nenahrává; false nikdy
ignoreoblasti vynechané z porovnání pixelů: { selector } nebo { rect: [x, y, w, h], viewport }, volitelně omezené přes viewports, locales, s poznámkou note
itemsstack 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
fieldsstack 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)
detailspojmenované čá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)
statesdalší 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ý? } }

Šipky (edges)

KlíčCo obsahuje
from, toid kroků
labeltext u šipky, třeba volba v rozhodnutí
kindmain (výchozí), nebo alt pro alternativní cestu

Snímky (capture)

KlíčCo obsahuje
formatwebp (výchozí), nebo png (bezeztrátový, pro tisk)
scale1 nebo 2 (pixely zařízení na snímku)
qualitykvalita WebP od 0,3 do 1
maskosobní ú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)
annotateočíslované značky u prvků kritérií s highlight
full_pagecelá stránka (výchozí, i u stránek stacku), nebo s false jen první obrazovka: u dlouhých stránek několikrát menší
screenshotthumb 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
recordtrue, step, flow, failed nebo off; viz kaloko walk --record
traceke 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í.

Kaloko · latest · 2026-11-21