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
schemavždy qawalk.config.v1
orgzkratka (slug) organizace na kaloko.app
projectprojekt 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_namená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ší
productzkratka produktu v Kaloku, jehož je projekt součástí; kaloko projects sync do něj projekt přidá
scenariosmasky souborů se scénáři
outputsložka běhů (výchozí tmp/kaloko)
environmentskde flow běží (níže)
browserchannel (kanál Playwrightu, třeba chrome; prázdný = přibalené Chromium) a port sdíleného prohlížeče (výchozí 9333)
walkvýchozí hodnoty pro každý běh: concurrency (jazyky najednou, 1–16), browsers, color_schemes, reduced_motion, forced_colors, display_modes
capturevýchozí hodnoty pro každý scénář: record, trace
evaluatebudget.calls: kolik nejvýš placených dotazů na evaluátor smí jedno vyhodnocení stát (níže)
evaluatorssémantický evaluátor jev, váš vlastní model a evaluátor obrázků vision (níže)
piiallow: údaje, které jako osobní jen vypadají (firemní kontakt), * znamená jakýkoli text; nemaskují se a kaloko share kvůli nim nezastaví
shareurl (výchozí https://kaloko.app), token_env (výchozí KALOKO_TOKEN), expires_days (výchozí 30)
docsnastavení changelogu a dokumentace (níže)
productsco 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
kindapp (výchozí), nebo design (složka živých HTML kroků)
base_urladresa, nebo jedna pro každý jazyk se záložní default; ${VAR} se doplní z proměnných prostředí (review aplikace)
readonlytrue pro produkci: CLI jen čte, nikdy se nepřihlašuje do administrací a nevytváří data
piiredact nebo pseudonymize: každý běh skryje osobní údaje; required: běh nevznikne, dokud je neskryje scénář nebo kaloko start --pii
blocked_pathsmasky cest, které běh jen pro čtení nikdy neotevře
allowed_post_pathsmasky cest, kam běh jen pro čtení smí poslat POST (košík)
may_create_datafalse zakáže vytváření dat (výchozí true)
accessochrana před celým prostředím: basic (user_env, password_env), headers (servisní tokeny), client_certificate a origins, které je dostanou
accountslidé, 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)
mailschránka: provider (mailpit, script, none), url, user_env, password_env, address, script, options, auth
apptestovaná aplikace pro každou platformu: android, ios, electron, desktop, windows
serve, fixtures, default_token_modedesignová prostředí: složka kroků, JSON fixtures, výchozí režim tokenů (starší název tokens_mode funguje dál)
token_modesdesignová 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)
originsdesignová 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_viewexperimentální: ke každému snímku statický HTML pohled

Evaluátory

KlíčCo obsahuje
evaluators.jev.api_key_envproměnná s vaším vlastním klíčem k evaluátoru (výchozí TYPESAFE_API_KEY)
evaluators.jev.hostedbez 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.thresholdsskóre pro pass a fail
evaluators.jev.model, base_url, max_state_chars, signals, concurrencyjemnější nastavení, potřeba jen výjimečně
evaluators.visiondruhý 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.textkterý evaluátor odpovídá na sémantické otázky jako první: jev (výchozí) nebo název vašeho vlastního
evaluators.escalate_tojev: odpovědi vašeho modelu, které na verdikt nestačí, se znovu zeptají JEV. Jen tímto směrem
evaluate.budget.callskolik 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.triageexperiment: 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.dirzdroje dokumentace (výchozí docs)
docs.changelogsoubor changelogu (výchozí CHANGELOG.md)
docs.stylekeep-a-changelog nebo release-notes
docs.version_sourceauto, git-tag, package.json, release-please, changesets, semantic-release, pyproject, cargo, gemspec, manual
docs.languagesjazyky dokumentace; první je jazyk originálů
docs.frameworkauto, docusaurus, vitepress, mkdocs, nextra, plain
docs.publishkdo čte: members, domain, nebo public (poslední dvě potřebují admina)
docs.imagesviewport 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á
filejeden 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.propertyvlastnost 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.propertyid 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_envpromě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_ctrprahy 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:

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á:

  1. v prostředí procesu,
  2. v .env vedle kaloko.config.yml,
  3. 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