Konfigurační soubor
kaloko.config.yml leží v kořeni repozitáře a říká CLI, kde vaše flow běží. kaloko init ho vytvoří i s komentáři, kaloko doctor ho zkontroluje. Jeho formát je qawalk.config.v1 a povinné jsou schema, org a environments.
schema: qawalk.config.v1
org: acme
project: shop
project_name: E-shop
scenarios: [qa/flows/*.yml]
environments:
local:
base_url: http://localhost:3000
staging:
base_url: https://staging.acme.test
access:
basic: { user_env: STAGING_USER, password_env: STAGING_PASSWORD }
accounts:
member: { user: qa@acme.test, password_env: MEMBER_PASSWORD }
production:
base_url: https://acme.com
readonly: true
blocked_paths: ["/account/**"]
walk:
browsers: [chromium]
share:
expires_days: 30
Klíče nejvyšší úrovně
| Klíč | Co obsahuje |
|---|---|
schema | vždy qawalk.config.v1 |
org | zkratka (slug) organizace na kaloko.app |
project | projekt v Kaloku pro běhy (jeho zkratka, třeba eco-podcasty); výchozí je název repozitáře. Scénář, který někdo přesunul do jiného projektu (v aplikaci nebo přes kaloko scenario move), tam zůstane: přesun má před tímto klíčem přednost |
project_name | název, který lidé v Kaloku vidí (ECO Podcasty). První kaloko share s ním chybějící projekt založí, kaloko projects sync existující přejmenuje. Sdílení běhu nikdy nepřejmenovává, jen upozorní, když se názvy liší |
product | zkratka produktu v Kaloku, jehož je projekt součástí; kaloko projects sync do něj projekt přidá |
scenarios | masky souborů se scénáři |
output | složka běhů (výchozí tmp/kaloko) |
environments | kde flow běží (níže) |
browser | channel (kanál Playwrightu, třeba chrome; prázdný = přibalené Chromium) a port sdíleného prohlížeče (výchozí 9333) |
walk | výchozí hodnoty pro každý běh: concurrency (jazyky najednou, 1–16), browsers, color_schemes, reduced_motion, forced_colors, display_modes |
capture | výchozí hodnoty pro každý scénář: record, trace |
evaluate | budget.calls: kolik nejvýš placených dotazů na evaluátor smí jedno vyhodnocení stát (níže) |
evaluators | sémantický evaluátor jev, váš vlastní model a evaluátor obrázků vision (níže) |
pii | allow: údaje, které jako osobní jen vypadají (firemní kontakt), * znamená jakýkoli text; nemaskují se a kaloko share kvůli nim nezastaví |
share | url (výchozí https://kaloko.app), token_env (výchozí KALOKO_TOKEN), expires_days (výchozí 30) |
docs | nastavení changelogu a dokumentace (níže) |
products | co vydáváte a verzujete jako celek (níže) |
traffic | čísla ze Search Console a GA4 ke stránkám, aby šly nálezy seřadit podle návštěvnosti (níže); traffic ve scénáři ho nahradí |
Prostředí
Každý klíč pod environments je název, který použijete v kaloko start --env.
| Klíč | Co obsahuje |
|---|---|
kind | app (výchozí), nebo design (složka živých HTML kroků) |
base_url | adresa, nebo jedna pro každý jazyk se záložní default; ${VAR} se doplní z proměnných prostředí (review aplikace) |
readonly | true pro produkci: CLI jen čte, nikdy se nepřihlašuje do administrací a nevytváří data |
pii | redact nebo pseudonymize: každý běh skryje osobní údaje; required: běh nevznikne, dokud je neskryje scénář nebo kaloko start --pii |
blocked_paths | masky cest, které běh jen pro čtení nikdy neotevře |
allowed_post_paths | masky cest, kam běh jen pro čtení smí poslat POST (košík) |
may_create_data | false zakáže vytváření dat (výchozí true) |
access | ochrana před celým prostředím: basic (user_env, password_env), headers (servisní tokeny), client_certificate a origins, které je dostanou |
accounts | lidé, kteří se přihlašují, pod stejnými klíči jako account ve scénáři: user nebo user_env, password_env, totp_env, storage_state (přihlášení uložené přes kaloko auth save) |
mail | schránka: provider (mailpit, script, none), url, user_env, password_env, address, script, options, auth |
app | testovaná aplikace pro každou platformu: android, ios, electron, desktop, windows |
serve, fixtures, default_token_mode | designová prostředí: složka kroků, JSON fixtures, výchozí režim tokenů (starší název tokens_mode funguje dál) |
token_modes | designová prostředí: režimy tokenů, ve kterých se vykreslí každý krok (bez něj všechny režimy sady; false jen default_token_mode) |
origins | designová prostředí: adresy, ze kterých design načítá písma, styly a obrázky (https://fonts.googleapis.com); organizace je povolí v Nastavení → Zabezpečení |
html_view | experimentální: ke každému snímku statický HTML pohled |
Evaluátory
| Klíč | Co obsahuje |
|---|---|
evaluators.jev.api_key_env | proměnná s vaším vlastním klíčem k evaluátoru (výchozí TYPESAFE_API_KEY) |
evaluators.jev.hosted | bez místního klíče vyhodnocuje z měsíčního limitu vašeho plánu (výchozí true); false použije jen váš klíč |
evaluators.jev.thresholds | skóre pro pass a fail |
evaluators.jev.model, base_url, max_state_chars, signals, concurrency | jemnější nastavení, potřeba jen výjimečně |
evaluators.vision | druhý evaluátor, který se dívá na screenshot (poskytovatel anthropic, klíč v ANTHROPIC_API_KEY); false ho vypne |
evaluators.<název> | váš vlastní textový evaluátor: kind: openai_compatible, base_url, model, případně api_key_env, concurrency (výchozí 2), max_state_chars (výchozí 24000; delší text stránky se zkrátí), timeout_ms, response_format (json_schema, json_object nebo none) |
evaluators.text | který evaluátor odpovídá na sémantické otázky jako první: jev (výchozí) nebo název vašeho vlastního |
evaluators.escalate_to | jev: odpovědi vašeho modelu, které na verdikt nestačí, se znovu zeptají JEV. Jen tímto směrem |
evaluate.budget.calls | kolik nových dotazů na JEV (vaším klíčem nebo přes Kaloko) smí jedno vyhodnocení položit, včetně předaných odpovědí; dotazy na váš vlastní model se nepočítají. Nejdřív přijdou na řadu kroky, pak vzorek každého stacku, vybraný podle priority (nejdřív stránky, které neprošly kontrolou, pak ty kontrolované nejdávněji). Co se nevejde, zůstane not_evaluated s poznámkou; kaloko evaluate --budget N limit přepíše |
evaluators.triage | experiment: Clef pojmenuje druh problému na každé obrazovce a ve snímcích z nahrávky, jen jako rada. model (clef nebo rychlejší clef-flash), keep (od jaké pravděpodobnosti se nález ukáže, výchozí 0,7), frames_per_step (0 nahrávky vynechá), cascade (Clef rozhodne kritéria, u kterých si textový evaluátor není jistý); false třídění vypne |
Místní model v Ollamě odpoví jako první a nejasné odpovědi předá JEV:
evaluate:
budget: { calls: 300 }
evaluators:
ollama:
kind: openai_compatible
base_url: http://localhost:11434/v1 # LM Studio: http://localhost:1234/v1
model: qwen3:8b
text: ollama
escalate_to: jev
Vlastní evaluátor se použije, jen když ho text jmenuje, a text stránky odchází jen na jeho base_url. Jeho verdikty jsou na plachtě i v komentáři k pull requestu označené „vyhodnotil váš vlastní model“.
Dokumentace a produkty
| Klíč | Co obsahuje |
|---|---|
docs.dir | zdroje dokumentace (výchozí docs) |
docs.changelog | soubor changelogu (výchozí CHANGELOG.md) |
docs.style | keep-a-changelog nebo release-notes |
docs.version_source | auto, git-tag, package.json, release-please, changesets, semantic-release, pyproject, cargo, gemspec, manual |
docs.languages | jazyky dokumentace; první je jazyk originálů |
docs.framework | auto, docusaurus, vitepress, mkdocs, nextra, plain |
docs.publish | kdo čte: members, domain, nebo public (poslední dvě potřebují admina) |
docs.images | viewport a locale (reader nebo jazyk) obrázků |
products.<slug> | name (text nebo pro každý jazyk), version (source, path, pattern), docs, project nebo projects, modules, reference_env, default_scenario, publish |
Bez products je produktem projekt.
Data o návštěvnosti
traffic připojí ke stránkám, které běh prošel, čísla z vyhledávání a analytiky. Chybějící popis u nejprodávanějšího produktu pak přijde na řadu dřív než stejná chyba na stránce, kterou nikdo nenajde. Dokud ho nepřidáte, nic se neděje, a dokud nenastavíte gsc nebo ga4, Kaloko se Googlu na nic neptá.
traffic:
file: qa/traffic/search-console-stranky.csv # export ze Search Console nebo GA4
gsc:
property: sc-domain:acme.cz # nebo https://www.acme.cz/
credentials_env: GOOGLE_APPLICATION_CREDENTIALS
ga4:
property: "123456789"
low_ctr: { min_impressions: 100, ratio: 0.5 }
| Klíč | Co dělá |
|---|---|
file | jeden nebo víc exportů CSV, cesta vůči souboru, který je uvádí: tabulka Stránky ze Search Console nebo přehled GA4 podle vstupních stránek. Kaloko čte české i anglické hlavičky (Stránka, Vstupní stránka, Page, URL, Landing page; Kliknutí/Clicks, Zobrazení/Impressions, CTR, Pozice/Position, Relace/Sessions, Konverze nebo Klíčové události) a čísla tak, jak je který jazyk píše (1 234, 1,234, 3,5 %) |
gsc.property | vlastnost Search Console. Kaloko se přihlásí jako servisní účet, přes searchAnalytics.query si řekne o kliknutí, zobrazení, CTR a pozici po stránkách za 28 dní končících předevčírem (délku změní days) a odpověď si pro běh uloží |
ga4.property | id vlastnosti GA4. Relace a klíčové události (conversions) podle vstupní stránky za 28 dní končících včera, přes Data API |
credentials_env | proměnná s cestou k JSON klíči servisního účtu, nebo přímo s JSONem (secret v CI). Výchozí GOOGLE_APPLICATION_CREDENTIALS. E-mail servisního účtu přidejte do vlastnosti Search Console jako uživatele a do GA4 jako čtenáře |
low_ctr | prahy kontroly HC127 (níže): stránky s aspoň min_impressions zobrazeními (výchozí 100), jejichž CTR je pod ratio (výchozí 0,5) násobkem mediánu webu |
Stránky se párují podle adresy: host bez www., cesta bez koncového lomítka a dotaz bez sledovacích parametrů (utm_*, gclid …); na schématu a kotvě nezáleží. Cesta z GA4 (/cs/eshop/zidle) se připojí, když stack prochází jeden host; stack přes víc hostů takové řádky vynechá a řekne to v stack.traffic.note. Průchod hostu, pro který data nemají vůbec žádný řádek (staging, náhled), najde čísla z produkce podle cesty, pokud ji data uvádějí jen u jednoho hostu. Sloupec CTR bez znaku % se čte jako procenta, když je v něm některá hodnota větší než 1, jinak jako podíl. Když je stránka v exportu i v odpovědi API, platí čísla z API, nesčítají se. Okno pro API se počítá od začátku běhu, takže každé sestavení jednoho běhu pracuje se stejnými čísly.
Co z toho máte:
- každá stránka stacku má v
items.jsontraffic: { clicks, impressions, ctr, position, sessions, conversions }a index stránek na plachtě dostane sloupce Zobrazení a Kliknutí, podle kterých jde řadit; kaloko export findingspřidá tytéž sloupce aimpacta nálezy s největším dopadem dá nahoru.impact = váha × (zobrazení + 10 × (kliknutí + relace) + 100 × konverze), kde váha je 3 u chyby nebo nesplněného kritéria přijetí a 1 u varování. Stránka bez čísel má dopad 0;- stack s packem
seodostane HC127: stránky s hodně zobrazeními, jejichž CTR je pod polovinou mediánu webu na podobných pozicích (1–3, 4–10, 11–20, každá skupina aspoň s pěti stránkami k porovnání). Obvykle to znamená, že titulek a popis ve výsledcích chtějí přepsat. Bez dat o návštěvnosti se kontrola vůbec neobjeví.
Zdroj, který nejde přečíst, Kaloko ohlásí na stderr a vynechá; běh se sestaví i tak. Klíč servisního účtu nikdy neopustí váš počítač a do běhu se nezapíše; viz Bezpečnost a vaše data.
Tajné údaje
Tajné údaje do konfigurace nikdy nepatří. Kde je nějaký potřeba, konfigurace jen pojmenuje proměnnou prostředí (password_env: STAGING_PASSWORD, { env: CF_ACCESS_CLIENT_SECRET }). Kaloko hodnotu hledá:
- v prostředí procesu,
- v
.envvedlekaloko.config.yml, - v
~/.config/kaloko/.env.
Proměnná, která už je nastavená, má přednost před soubory. Hodnoty se odstraní ze zachyceného HTML, z textu stránky i z výstupu konzole. kaloko doctor řekne, které pojmenované proměnné chybí. Token pro sdílení je KALOKO_TOKEN, pokud share.token_env neříká jinak; viz Role a tokeny.
Kaloko · latest · 2026-11-21