Nápověda Kaloka

Jak Kaloko nastavit, projít aplikaci s agentem, zkontrolovat, co postavil, a z výsledku vést changelog a dokumentaci. Obrázky pocházejí ze schválených běhů samotného Kaloka, takže ukazují obrazovky tak, jak vypadají dnes. I tahle nápověda je živá dokumentace publikovaná v Kaloku.

Tutoriály #

• První běh za deset minut: instalace, přihlášení, průchod flow, sdílení a kontrola
• Navrhněte flow se svým agentem: živé HTML kroky, verze a reference designu

Kontrola a schválení #

• Projít běh: obrazovky běhu na plachtě jednu po druhé
• Schválit nebo vrátit běh: schválit kroky, které sedí, a vrátit ty ostatní
• Kontrolovat jen to, co se změnilo: režim kontroly, jeho klávesy a převzatá schválení
• Co je nového: novinky s obrázky před a po
• Předat podepsaný záznam o přijetí: doklad, kdo co převzal, a jak ho ověřit

Průchod a kontroly #

• Napsat scénář: flow, jeho kroky a co má každý krok ukázat
• Přidat kritéria a packy kontrol: automatické kontroly, otázky pro evaluátor, packy
• Projít víc prohlížečů a zařízení: WebKit, Firefox, telefony, tablety, tmavý režim
• Projít aplikace pro Android, iOS a desktop: emulátory, simulátory, Electron, macOS a Windows
• Natočit video průchodu: video a průběh každého kroku, jedno video celého běhu
• Spouštět Kaloko v CI a komentovat pull requesty: průchod každého preview nasazení
• Porovnat s referenčním během a ignorovat, co se mění pořád: rozdíly bez hodin a karuselů
• Kontrolovat stránky podle plánu (hostované běhy): prohlížeče Kaloka otevřou vaše stránky každý den nebo týden

Tým a přístup #

• Pozvat lidi a hosty: členové, hosté v jednotlivých projektech, čtenáři z vaší domény
• Role a API tokeny: kdo smí co, tokeny pro agenty a CI
• Nastavit firemní přihlášení: přihlašovací domény, dvoufázové ověření, SAML, OIDC a SCIM
• Připojit Jiru, Linear, Slack a Teams: úkoly z kroků a kanály po projektech

Changelog a dokumentace #

• Publikovat changelog s obrázky: připravit záznam, zapsat release, nasdílet ho
• Publikovat živou dokumentaci a hlídat zastaralé části: návody, jejichž obrázky drží krok s aplikací
• Exportovat dokumentaci a changelog: Markdown, Docusaurus, VitePress, MkDocs, HTML, PDF nebo JSON

Reference #

• Příkazy CLI: všechny příkazy kaloko
• Soubor scénáře: všechny klíče scénáře
• Kritéria, kontroly a packy: všechny typy kontrol a co který pack přidá
• Konfigurační soubor: kaloko.config.yml
• Nástroje MCP: co agenti zvládnou přes MCP

Vysvětlení #

• Jak Kaloko odpovídá vašim aplikacím: organizace, produkty, projekty, moduly, prostředí a verze
• Jak vznikají verdikty: kontroly, evaluátor a lidé
• Bezpečnost a vaše data: co opustí váš počítač a kdo to uvidí

První běh za deset minut

Na konci tohoto návodu budete mít jedno flow své aplikace na plachtě v kaloko.app, nasdílené, se všemi obrazovkami ve všech jazycích a velikostech obrazovky, které scénář uvádí. Potřebujete Node 20 nebo novější, Chrome a aplikaci spuštěnou lokálně.

Nainstalujte CLI #

V kořeni projektu:

npm install --save-dev kaloko
npx kaloko init --agent claude --org <vaše-organizace>

Pro Codex použijte --agent codex, pro oba --agent all, a když budete CLI ovládat sami, volbu vynechte. init zapíše kaloko.config.yml a zkopíruje skill k vašemu agentovi. Zároveň si projekt přečte: framework, příkaz a adresu dev serveru, jazyky a hlavní cesty. Podle nich připraví první scénář qa/flows/main-pages.yml, takže první průchod funguje bez úprav.

Pokud organizaci ještě nemáte, nejdřív ji založte; stanete se jejím adminem.

Přihlaste tento počítač #

npx kaloko login
npx kaloko doctor

login otevře prohlížeč, kde kód schválíte a vyberete, co smí token dělat. Uloží se do ~/.config/kaloko/.env. doctor zkontroluje Node, Chrome, konfiguraci, prostředí a token a u každého ✕ napíše, co opravit.

Projděte flow #

Spusťte dev server a pak:

npx kaloko start --scenario qa/flows/main-pages.yml --env local
npx kaloko walk
npx kaloko preview

start založí běh, walk otevře v prohlížeči každý krok, zachytí ho a průběžně spouští kontroly. Na konci vypíše verdikty: co neprošlo a na co se má podívat člověk. preview vypíše cestu k místní plachtě, která se otevře přímo z disku.

S nainstalovaným skillem nemusíte nic psát a stačí požádat agenta: „Projdi s Kalokem hlavní stránky na localu a ukaž mi, co neprochází.“ Spustí stejné příkazy.

Nasdílejte ho #

npx kaloko share

Běh se nahraje do kaloko.app a příkaz vypíše odkaz. Na větvi s pull requestem přidá share --pr odkaz i do komentáře v pull requestu.

Podívejte se a rozhodněte #

Otevřete odkaz. Běh se ukáže jako mapa kroků; kliknutím na krok uvidíte snímek, kritéria a co se zjistilo.

Kroky, které sedí, schvalte, ostatní vraťte s poznámkou, a až budete spokojeni, běh přijměte. Váš agent si poznámky přečte přes kaloko feedback.

Kam dál #

• Napište scénář pro flow, na kterém vám záleží nejvíc.
• Projít běh ukáže plachtu podrobněji.
• Spouštějte ho v CI u každého pull requestu.
• Přehled CLI uvádí všechny příkazy.

Navrhněte flow se svým agentem

V tomto návodu navrhnete obrazovky jednoho flow jako živé HTML se svým agentem, necháte tým, ať je okomentuje, publikujete verzi a uděláte z ní návrh, se kterým se porovná každá implementace. Potřebujete projekt, ve kterém už proběhl kaloko init, a scénář pro dané flow, třeba qa/flows/checkout.yml.

Přidejte designové prostředí #

Designové prostředí je složka, kterou CLI při průchodu servíruje. Přidejte ho do kaloko.config.yml:

environments:
  design: { kind: design, serve: design }

Scénář zůstává stejný, jaký používá vývoj a QA: stejné kroky, stejná kritéria. Návrh se tak podle akceptačních kritérií zkontroluje dřív, než ho někdo začne stavět.

Nechte agenta nakreslit kroky #

Požádejte agenta, s jakýmkoli design skillem, který váš tým používá:

Navrhni checkout flow do design/ podle našeho brand skillu: jedna složka na každý krok z qa/flows/checkout.yml, sdílené CSS v design/_shared, tokeny v design/tokens.json. Pak spusť kaloko walk a kaloko sync.

Z každého kroku vznikne design/<krok>/index.html: obyčejné HTML, CSS a JS, které se otevře i z disku. Odkazy mezi kroky jsou relativní, třeba ../payment/index.html.

Projděte, zkontrolujte a synchronizujte #

npx kaloko start --scenario qa/flows/checkout.yml --env design
npx kaloko design lint
npx kaloko walk
npx kaloko sync

design lint zkontroluje složku podle pravidel přenosného HTML: relativní adresy, žádné CDN, žádné úložiště v prohlížeči, předvídatelný obsah. walk vykreslí jen kroky, které se změnily, a sync je uloží do společného konceptu a převezme kroky, které změnili ostatní.

Komentujte společně #

Tým otevře koncept na plachtě, proklikne si živé kroky a připíná komentáře k prvkům. Každý vidí, kdo se právě dívá. Agent si komentáře přečte přes kaloko feedback, upraví, o co žádají, a synchronizuje znovu.

Publikujte verzi #

npx kaloko share --name "Checkout v2"

Tím publikujete verzi celého flow, třeba „v2 · 3 změněné, 17 beze změny“. Nezměněné kroky se ukládají jen jednou. share --notes-preview vám před publikováním ukáže poznámky o tom, co se změnilo.

Udělejte z ní referenci #

Až verzi někdo přijme, nastavte ji jako referenci designu (od plánu Team):

npx kaloko reference --design --version 2

U kroků implementace ve scénáři zapněte packs: [design]. Od plánu Business se pak každý běh implementace porovná s referencí: pixely, struktura, tokeny a kontrast, a kaloko drift napíše, který token použít tam, kde se kód liší.

Když máte návrh ve Figmě #

Pokud návrh už žije ve Figmě, kaloko design import figma <adresa-souboru> --scenario qa/flows/checkout.yml udělá z framů designové kroky a z proměnných tokeny. Složka framů vyexportovaných z Figmy funguje i bez tokenu.

Projít běh

Běh je jeden průchod agenta flow: každá obrazovka, na kterou se dostal, ve všech jazycích a velikostech obrazovky, se vším, co zkontroloval. Projdete ho v prohlížeči, nic se neinstaluje.

Otevřete běh #

1. Otevřete odkaz z pull requestu, z issue nebo z e-mailu. Běh se otevře na plachtě: všechny kroky flow jako mapa se šipkami, které ukazují cestu mezi nimi.

   

2. Pokud vám víc vyhovuje seznam, stiskněte I. Stejný běh se ukáže jako seznam kroků s výsledky a dá se v něm hledat i filtrovat podle stavu.

   

Podívejte se na krok #

1. Klikněte na krok. V detailu uvidíte snímek obrazovky, kritéria s tím, co se zjistilo, a komentáře, které k němu lidé napsali. Šipkami ← a → přejdete na předchozí a další krok.

   

2. Něco nesedí? Napište ke kroku komentář. Všechny otevřené komentáře běhu najdete v panelu komentářů, takže se mezi kroky nic neztratí.

   

Projděte ho jako uživatel #

Klávesou R spustíte průchod během: jedna obrazovka po druhé, v pořadí, v jakém je uvidí člověk. Tak nejrychleji ukážete flow někomu, kdo plachtu ještě neviděl.

Až budete vědět, co si myslíte, schvalte nebo vraťte běh.

Schválit nebo vrátit běh

Teprve vaše rozhodnutí udělá z „agent říká, že je hotovo“ opravdu hotovou věc. Rozhodujete po krocích a pak za celý běh.

Rozhodněte o každém kroku #

1. Otevřete krok a přečtěte si jeho kritéria. Zelené kritérium zkontrolovalo Kaloko; u kritéria, které potřebuje člověka, to stojí přímo u něj a rozhodnutí je na vás.

   

2. Když krok sedí, zvolte pod komentáři Schválit. Když ne, napište, co se má změnit, a zvolte Zamítnout: „celková cena poskočí, když se načte cena“, ne „oprav to“. Agent si poznámku přečte a podle ní pokračuje.

Rozhodněte o běhu #

1. Když jsou schválené všechny kroky, zvolte Přijmout běh. Běh se stane obrázkem této verze: novinky i dokumentace od té chvíle ukazují jeho obrazovky.
2. Pokud se má něco nejdřív změnit, zvolte Vrátit běh. Kdo ho sdílel, dostane vaše poznámky; až nasdílí další běh, komentář v pull requestu ukáže na něj.

   

Příště to bude kratší #

V dalším běhu si kroky, jejichž obrazovky se nezměnily, vaše schválení ponechají. Díváte se jen na to, co je nové nebo jiné, a na plachtě je vidět, která schválení se přenesla a z kterého běhu.

Agenti mohou komentovat a navrhovat, ale běh přijímá jen člověk.

Co je nového

Každé vydání produktu má v novinkách záznam psaný pro lidi, kteří produkt používají, s obrazovkami, které změnilo. Obrázky jsou ze schválených běhů, takže ukazují to, co někdo schválil.

Kde novinky najdete #

1. V hlavní nabídce otevřete Produkty a u produktu zvolte Novinky, nebo otevřete odkaz, který vám někdo poslal. Každý produkt má své novinky a nejnovější vydání je nahoře.
2. Verze v horní části vás přenesou na své vydání. Pod každou verzí je, co se v ní změnilo, rozdělené na Nové, Změny, Opravy a Odebráno.

Porovnejte předtím a potom #

1. U změněné obrazovky leží obrázek předtím a potom přes sebe. Posuvníkem posunete předěl.
2. Vedle sebe dá oba obrázky vedle sebe (na telefonu pod sebe).
3. Jazyk a Obrazovka přepnou všechny obrázky do jiného jazyka nebo velikosti obrazovky, pokud je běh zachytil.
4. Otevřít flow na plachtě ukáže celé flow, pokud máte k běhu přístup.

Buďte v obraze #

• Posílat e-mail o novinkách: ke každému novému vydání vám přijde jeho záznam s obrázky ve vašem jazyce. Odkaz na konci každého e-mailu je zase vypne.
• Stáhnout nabídne novinky jako JSON, Markdown, HTML pro offline čtení nebo PDF, třeba pro poznámky k vydání nebo zprávu pro klienta.
• Veřejné novinky mají i odběr pro čtečky.

Kontrolovat jen to, co se změnilo

Režim kontroly ukazuje jeden krok po druhém a začíná těmi, které chtějí člověka: nesplněné a vrácené kroky, kritéria, kterými si AI nebyla jistá, kroky změněné od posledního přijatého běhu a kroky s otevřenými komentáři. Kroky, které se nezměnily, si ponechají schválení, které jim někdo dal dřív.

Otevřete režim kontroly #

1. Otevřete odkaz na kontrolu z pull requestu nebo z e‑mailu (končí #review), nebo otevřete běh a stiskněte Q.

   

2. Krok, o kterém rozhodujete, je vedle přijatého běhu, takže vidíte, co se pohnulo.

Rozhodujte z klávesnice #

Když jsou rozhodnuté všechny kroky, celý běh přijměte, nebo vraťte.

Podívejte se zblízka #

Ve velkém náhledu porovnáte oba běhy vedle sebe, jako rozdíl, posuvníkem (táhnete dělicí čáru přes oba screenshoty) nebo prolnutím (tento běh průsvitně přes ten druhý). Když chcete ukázat na problém, nakreslete při psaní komentáře do screenshotu rámeček, šipku nebo čáru, nebo vložte obrázek.

Převzatá schválení #

U převzatého schválení je vidět, kdo ho dal a ve kterém běhu. Když si myslíte, že se má krok projít znovu, schválení zrušte a krok bude znovu čekat. Převzaté schválení za vás běh nikdy nepřijme.

Předat podepsaný záznam o přijetí

Když se klient nebo auditor zeptá, kdo release převzal, dejte mu záznam o přijetí běhu. Je v něm, kdo co a kdy schválil, výsledky kritérií a otisk každého screenshotu, a Kaloko ho podepíše. Záznamy jsou součástí plánů Business a Enterprise.

Stáhněte ho #

1. Otevřete přijatý běh a jeho panel Záznam o přijetí.

   

2. Pro lidi zvolte Stáhnout PDF, pro systém, který záznamy archivuje, JSON. PDF nese stejný JSON uvnitř.

Běh, který přijatý není, záznam nemá. Nejdřív ho přijměte, nebo o to požádejte toho, kdo to má udělat.

Ověřte záznam, který jste dostali #

Záznam ověří kdokoli i bez účtu. Vývojáři spustí kaloko signoff --verify zaznam.pdf; příkaz zkontroluje podpis proti veřejnému klíči Kaloka a řekne, jestli se v záznamu něco změnilo. Stačí upravit jediný znak a ověření neprojde.

Připojit Jiru, Linear, Slack a Teams

Pro adminy organizací v plánu Team a vyšších. Po připojení lidé založí z vráceného kroku úkol přímo na plachtě a každý projekt dá vědět do svého kanálu, co se stalo.

Jira nebo Linear #

1. Otevřete Nastavení → Integrace a připojte Jira Cloud (přihlášením přes Atlassian, nebo vložením API tokenu) či Linear (přihlášením, nebo vložením API klíče).
2. Každý projekt v Kaloku přiřaďte k projektu a typu úkolu v Jiře, nebo k týmu v Linearu. Výchozí řádek pokryje projekty, které nevyjmenujete.
3. U Jiry přidejte do svého webu Jira webhook, který vám Kaloko ukáže, aby dokončený úkol hned uzavřel svůj komentář v Kaloku. Bez něj to Kaloko kontroluje každých 30 minut.

Lidé pak u kroku zvolí Nové issue. Úkol dostane screenshot, kritérium a poznámky kontrolujících i s odkazem zpět.

Kanály ve Slacku nebo Teams #

1. V Nastavení → Integrace přidejte k projektu kanál: pro Slack tlačítkem Add to Slack, pro Microsoft Teams adresou toku z Workflows.
2. Zaškrtněte události, které kanál chce: nový běh, vrácení, přijetí, komentář, zmínka, zapsaný release.
3. Nastavte tiché hodiny, když kanál nemá od Kaloka v noci nic slyšet; zprávy počkají, až skončí.

Omezený projekt hlásí jen do kanálů, které ho výslovně jmenují. Kanál ve Slacku pro celou organizaci funguje dál.

Napsat scénář

Scénář je flow, které Kaloko projde: soubor YAML s obrazovkami, cestou mezi nimi a tím, co má každá obrazovka splňovat. Scénáře k úkolům bývají u úkolu (docs/tasks/TASK-123/qa/scenario.yml), dlouhodobá flow, třeba pokladna, v qa/flows/.

Nechte ho napsat agenta #

S nainstalovaným skillem nemusíte psát YAML, stačí zadání:

Přečti si úkol v docs/tasks/TASK-123, napiš k němu akceptační plán a scénář pro Kaloko a zvaliduj ho.

Agent napíše dva soubory: ACCEPTANCE.md pro lidi (cíl, kroky, kritéria AC1, AC2…) a scénář pro běh. Když se zadání změní, upraví nejdřív plán a potom scénář.

Z čeho se soubor skládá #

schema: qawalk.scenario.v1
id: TASK-123-checkout
title: Pokladna
kind: task                # task | flow
product: shop             # volitelné, s module:
locales: [cs, en]
viewports:
  desktop: [1280, 800]
  mobile: [390, 844]
environments: [local, staging]
nodes:
  - id: cart
    kind: screen
    title: Košík
    path: /cart
    purpose: Návštěvník vidí, co kupuje, a může pokračovat k platbě.
    execution:
      strategy: playwright   # playwright | agent | manual
      script: steps/cart.mjs
    criteria:
      - id: AC1
        text: Stránka má právě jeden hlavní nadpis.
        check: { type: deterministic, assert: count, selector: h1, min: 1, max: 1 }
edges:
  - { from: cart, to: payment, label: pokračovat }

• Id kroků (cart) neměňte: odkazují na ně odkazy, komentáře, schválení i obrázky v dokumentaci.
• purpose je jedna věta o tom, k čemu obrazovka slouží. Čte ji evaluátor.
• execution říká, kdo se na obrazovku dostane: skript v Playwrightu, agent, který ji zachytí přes kaloko capture, nebo člověk.
• Další druhy uzlů: decision pro větvení, email pro zprávu ze schránky, stack pro mnoho stránek jedné šablony.

Všechny klíče najdete v referenci souboru scénáře. Jak přidat kontroly, popisuje návod Přidat kritéria a packy kontrol.

Zkontrolujte ho #

npx kaloko validate qa/flows/checkout.yml
npx kaloko validate qa/flows/checkout.yml --coverage

validate ověří schéma a odkazy mezi kroky. --coverage porovná kritéria s akceptačním plánem a vypíše, co plán chce a scénář nekontroluje.

Začněte od veřejných stránek #

U marketingového webu nebo dokumentace začněte konceptem:

npx kaloko draft https://example.com/ https://example.com/pricing

Kaloko stránky stáhne a napíše k nim produkční scénář jen pro čtení i s plánem. Jako účel použije titulek, H1 a popis stránky a přidá packy seo, a11y, perf a console. Přidá i krok s adresou, která neexistuje, takže se zkontroluje i stránka 404. Pak účel každé stránky upřesněte a doplňte, co musí opravdu splňovat.

Přidat kritéria a packy kontrol

Každý krok má svá kritéria: co musí obrazovka splňovat. Kaloko zná tři druhy a dobrý scénář použije ten nejjednodušší, který na otázku odpoví.

Dá se spočítat: deterministická kontrola #

Co se dá spočítat nebo přečíst ze stránky, se ověří přímo ve stránce a k výsledku se přiloží důkaz:

criteria:
  - id: AC1
    text: Košík ukazuje dvě položky.
    check: { type: deterministic, assert: count, selector: ".cart-item", min: 2, max: 2 }
  - id: AC2
    text: Po zaplacení se zobrazí poděkování.
    check: { type: deterministic, assert: url_matches, pattern: "/thanks$" }
  - id: AC3
    text: Tlačítko Zaplatit má barvu značky.
    check: { type: deterministic, assert: style_equals, selector: "button.pay", property: background-color, token: color.brand.primary }

Další kontroly čtou text, atributy, HTTP status, přetečení na telefonu nebo hodnotu, kterou stránka vystavuje (js_equals). Celý seznam je v referenci kontroly a packy. Skript kroku nikdy nemusí nechávat značku, kterou by kritérium hledalo.

Otázka: sémantická kontrola #

Co chce úsudek, dostane evaluátor jako otázku ke stránce:

  - id: AC4
    text: Hlavní výzva k akci je zřejmá.
    check: { type: semantic, question: Ukazuje stránka jednu zřetelnou hlavní výzvu k akci?, scope: main }

Evaluátor si přečte zredukovanou osnovu stránky a odpoví skóre. Jasné ano projde, jasné ne neprojde a všechno mezi tím rozhodne člověk. Když jde o vzhled (rozložení, obrázky, „vypadá to jako naše značka“), přidejte ke kontrole vision: true: na screenshot se pak podívá ještě model, který vidí obrázky. Používejte to jen u kroků, kde je to potřeba.

Rozhodne člověk: ruční kontrola #

  - id: AC5
    text: Právníci schválili znění souhlasu.
    check: { type: manual }

Ruční kritérium zůstane „nehodnoceno“, dokud o něm kontrolující nerozhodne na plachtě.

Packy kontrol #

Pack přidá ke kroku hotovou sadu kritérií, takže běžné kontroly nepíšete ručně:

nodes:
  - id: home
    packs: [seo, a11y, perf, console]

Limit změníte vlastním kritériem se stejným id, jaké má pack (třeba AC401 pro LCP); vaše kritérium má přednost. Jak se z výsledků skládá verdikt, vysvětluje stránka jak vzniká verdikt.

Projít víc prohlížečů a zařízení

Běh ve výchozím stavu zachytí každý krok v Chromiu, v každém jazyce a viewportu scénáře. Přidat můžete další prohlížeče, předvolby zařízení, tmavý režim a několik dalších nastavení. Každá kombinace je samostatný snímek, takže přidávejte jen to, o čem úkol je: chyba v Safari potřebuje WebKit u dotčených kroků, ne všechna nastavení u všech kroků.

Ve scénáři #

viewports: [iphone-se, iphone-15, pixel-8, ipad-landscape, laptop]
browsers: [chromium, webkit, firefox]
color_schemes: [light, dark]
reduced_motion: [no-preference, reduce]   # volitelné
forced_colors: [none, active]             # volitelné, vysoký kontrast ve Windows
display_modes: [browser, standalone]      # volitelné, stránka jako nainstalovaná webová aplikace

Výchozí hodnoty pro celý projekt patří pod walk: v kaloko.config.yml. Příkazová řádka má přednost před scénářem a scénář před konfigurací.

Pro jeden běh #

npx kaloko start --scenario qa/flows/checkout.yml --env staging \
  --browsers chromium,webkit --color-schemes light,dark --viewports iphone-se,pixel-8,desktop-hd
npx kaloko walk                      # jeden průchod pro každý prohlížeč a zařízení
npx kaloko walk --browsers webkit    # jen snímky běhu ve WebKitu

Předvolby zařízení #

npx kaloko devices vypíše předvolby: telefony (iphone-se, iphone-15, pixel-8, galaxy-s24…), skládací telefony (fold-folded, fold-open), tablety (ipad-portrait, ipad-landscape…), počítače (laptop, desktop-hd, desktop-wide) a tv-1080p. Přípona -landscape otočí telefon, skládačku nebo tablet na šířku (iphone-15-landscape). Předvolba nastaví velikost, poměr pixelů, dotyk a user agent zařízení. Odhalí chyby rozložení, zbytek najde až skutečné zařízení.

Nainstalujte prohlížeče #

WebKit (jádro Safari) a Firefox stáhnete jednou na každý počítač nebo job v CI:

npx kaloko browser install --browsers webkit,firefox

npx kaloko doctor vypíše prohlížeče, které vaše scénáře potřebují, a řekne, jak doinstalovat chybějící. V CI na Linuxu přidejte --with-deps kvůli systémovým knihovnám.

Co čekat #

• Několik kontrol běží jen v Chromiu: názvy ze stromu přístupnosti, viditelný focus a posuny rozložení, ve WebKitu navíc průchod tabulátorem. V ostatních prohlížečích jsou „nehodnoceno“ i s důvodem a krok kvůli nim není částečně splněný.
• Kontrast se kontroluje pro každé barevné schéma zvlášť, takže chyba kontrastu v tmavém režimu neprojde na tmavém snímku.
• Běh odmítne víc než 400 kombinací.

Na plachtě najdete přepínač prohlížeče, barevného schématu a dalších nastavení vedle přepínače jazyka. Detail kroku s předvolbou zařízení vykreslí jeho rámeček a volba Vedle: ukáže stejný krok v jiném prohlížeči nebo schématu vedle něj.

Projít aplikace pro Android, iOS a desktop

Nativní aplikace Kaloko prochází stejně jako webové stránky: z každého kroku je screenshot s UI stromem, zkontrolovaná kritéria a místo na plachtě. Scénář říká, o jakou platformu jde, a konfigurace, kterou aplikaci otevřít.

1. Pojmenujte aplikaci pro každé prostředí #

# kaloko.config.yml
environments:
  staging:
    app:
      android: { package: com.acme.shop.staging, apk: build/app-staging.apk, reset: true }
      ios: { bundle: com.acme.shop, app: build/Shop.app, device: iPhone 17 }
  desktop:
    app:
      electron: { main: dist/main.js }
      # desktop: { name: Notes }                         # aplikace pro macOS podle okna
      # windows: { name: contoso, path: dist/Contoso.exe }

2. Nastavte platformu ve scénáři #

platform: android        # android | ios | electron | desktop | windows
devices: [pixel-8-api-34, pixel-7-api-33]
color_schemes: [light, dark]
nodes:
  - id: product
    kind: screen
    path: shop://product/42     # deep link
    packs: [app]

Na kroky se aplikace dostane přes deep link nebo skriptem kroku (app.tap(…), app.type(…)). V každém jazyce se aplikace spustí znovu a v daném jazyce, reset: true nejdřív smaže její data.

Co která platforma umí #

Pack app kontroluje popisky ovládacích prvků, velikost dotykových ploch, useknutý text a pády.

Obrazovky z jiných nástrojů #

Screenshot může pořídit Maestro, Appium, XCUITest, Detox nebo člověk a Kaloko ho rozloží i s UI stromem:

npx kaloko capture --step checkout --image shot.png --tree hierarchy.xml --device "Pixel 8" --density 2.625

--tree přečte XML z uiautomatoru nebo Appia, idb ui describe-all --json a JSON hierarchie z Maestra. Bez stromu přečte --ocr text z obrázku (na macOS). Celou složku screenshotů nebo report testů nahrajete přes npx kaloko import.

Nejdřív zkontrolujte počítač #

npx kaloko doctor

Vypíše, které nástroje pro aplikace na počítači chybějí (adb, simctl, idb, ffmpeg), a jak je nainstalovat. Na macOS si kaloko doctor --fix vyžádá oprávnění k nahrávání obrazovky a zpřístupnění, která desktopové snímky potřebují.

Natočit video průchodu

Screenshot ukáže, kde krok skončil. Video ukáže, jak se tam dostal: točící se kolečko, které se nezastavilo, menu, které se otevřelo dvakrát. Nahrávejte, když screenshot neukáže, co má kontrolující posoudit: animace, načítání, přetahování, krok, který jednou projde a jednou ne, nebo ukázku pro klienta.

Nahrajte průchod #

npx kaloko walk --record           # každý krok od předchozí obrazovky po jeho snímek
npx kaloko walk --record flow      # celý průchod pro každý jazyk, kapitola na krok
npx kaloko walk --record failed    # jen kroky, kterým selže skript nebo kontroly
npx kaloko walk --record --record-quality low --steps checkout

Pokud chcete nahrávat vždy, nastavte to ve scénáři nebo v kaloko.config.yml:

capture:
  record: { mode: failed, quality: low, max_seconds: 45 }
nodes:
  - id: checkout
    record: true        # tento krok vždy; record: false nikdy

Kvalita je low, medium (výchozí) nebo high. Videa jsou mnohem větší než screenshoty, takže nenahrávejte každý průchod.

Průběh má každý webový krok #

Každý prošlý webový krok si nechá průběh: kliknutí a psaní, síťové požadavky se statusem a časem a zprávy z konzole. Je malý a zapnutý ve výchozím stavu; vypne ho --no-trace.

npx kaloko video list                    # co se nahrálo a zaznamenalo, i s velikostí
npx kaloko video trace --step checkout   # průběh kroku jako časová osa v terminálu

Na plachtě najdete v detailu kroku vedle snímku přepínač Video a na záložce Technické průběh. Klikněte na řádek a video na to místo skočí. Přehrání běhu pustí video celého flow po kapitolách.

Udělejte z běhu jedno video #

npx kaloko video export --format mp4     # nebo webm, gif
npx kaloko video export --locale cs --steps cart,payment --lang cs --out checkout.mp4

Export seřadí videa podle flow a před každý krok dá úvodní kartu s jeho názvem a verdiktem. Takový soubor pošlete klientovi nebo přiložíte k poznámkám k vydání.

Potřebné nástroje #

Videa z webu a z Electronu potřebují jen Chrome. S nainstalovaným ffmpeg dostanete i MP4 pro Safari, videa aplikací (Android, iOS Simulator, macOS) a export celého průchodu. npx kaloko video tools vypíše, co na počítači je. Průchody ve WebKitu a Firefoxu se nenahrávají a průběh se u nich nezaznamenává.

Sdílení #

Nahrávat můžete v každém plánu. kaloko share nahraje videa spolu s během v plánech Business a Enterprise; ve Free a Team zůstanou v místním náhledu a sdílí se screenshoty a průběhy. Sdílená videa se uchovávají 30 dní (Enterprise si dobu nastaví v Nastavení → Úložiště). Video větší než 25 MB zůstane jen u vás: snižte kvalitu nebo max_seconds.

Spouštět Kaloko v CI a komentovat pull requesty

V CI spouští Kaloko stejné příkazy jako na vašem počítači. Obvyklé nastavení projde na preview nasazení (Vercel, Netlify, Cloudflare Pages nebo jakákoli review app) to, co pull request změnil, a odkaz na plachtu napíše do komentáře v pull requestu.

1. Napište workflow #

npx kaloko ci github     # zapíše .github/workflows/kaloko.yml
npx kaloko ci gitlab     # zapíše kaloko.gitlab-ci.yml; vložte ho do .gitlab-ci.yml přes include
npx kaloko ci github --print   # jen ukáže, nic nezapíše

--scenario a.yml,b.yml ho omezí na vybrané scénáře. Příkaz zároveň přidá do kaloko.config.yml prostředí preview s base_url: ${KALOKO_PREVIEW_URL}. Scénář, který vyjmenovává environments:, musí obsahovat i preview, jinak ho kaloko start odmítne; příkaz vám řekne, kterých scénářů se to týká.

2. Přidejte token #

V Nastavení → API tokeny vytvořte token s rolí tester a přidejte ho do tajných proměnných CI v repozitáři jako KALOKO_TOKEN. Na GitLabu přidejte ještě KALOKO_GITLAB_TOKEN: project access token s rozsahem api, aby Kaloko mohlo napsat poznámku do merge requestu. Workflow commitněte.

Co workflow dělá #

Po každém úspěšném preview nasazení pull requestu:

1. Nainstaluje projekt a prohlížeč (npx kaloko browser install --with-deps), a když o ně scénář žádá, i WebKit a Firefox.
2. npx kaloko ci preview-url --wait 600 --github-env najde adresu preview, pull request a jeho základní větev a předá je dál jako KALOKO_PREVIEW_URL, KALOKO_PR a KALOKO_BASE.
3. U každého scénáře kaloko affected --check zjistí, jestli změna zasahuje některý jeho krok. Pokud ne, scénář přeskočí, jinak spustí:

npx kaloko start --scenario qa/flows/checkout.yml --env preview
npx kaloko walk --ephemeral --affected
npx kaloko share --pr

share --pr přidá do pull requestu jeden komentář za každý scénář a při dalších pushích ho aktualizuje. Soubory se posílají podle obsahu, takže nezměněné screenshoty se znovu nenahrávají.

Dobré vědět #

• walk --affected potřebuje historii gitu: na GitHubu checkout s fetch-depth: 0, na GitLabu GIT_DEPTH: "0".
• --trigger pull_request spouští workflow při každém pushi místo události nasazení a na preview počká.
• kaloko ci preview-url vypíše jen adresu, takže funguje v jakémkoli CI: export KALOKO_PREVIEW_URL="$(npx kaloko ci preview-url)".
• Preview chráněné Vercel deployment protection potřebuje tajnou proměnnou VERCEL_AUTOMATION_BYPASS_SECRET a blok access.headers prostředí preview, který je ve vygenerované konfiguraci zakomentovaný.
• V pull requestu se komentář neobjevil? Obvykle chybělo preview nasazení nebo token. Log jobu řekne, co z toho.

Pokud vaše vydání publikuje release-please, changesets nebo semantic-release, přidá npx kaloko ci github --release druhé workflow, které každé vydání zapíše do Kaloka. Všechny volby najdete v referenci CLI.

Porovnat s referenčním během a ignorovat, co se mění pořád

Před vydáním chcete znát jednu odpověď: co vypadá jinak než verze, kterou tým přijal, a jestli je to záměr. Dobrý běh scénáře se stane jeho referencí a každý další běh se s ní porovná.

Nastavte referenci #

Na plachtě otevřete běh, se kterým jste spokojení, zvolte Přijmout běh a potom Nastavit jako referenci. Každý scénář má jednu referenci a ta se změní, jen když někdo nastaví novou. Z terminálu:

npx kaloko reference --scenario checkout --baseline --run <run-id>
npx kaloko reference --scenario checkout                     # ukáže současnou

Porovnejte běh #

Na plachtě zvolte Porovnat a referenci (nebo předchozí běh, případně jakýkoli jiný běh scénáře). Každý krok dostane štítek s podílem změněných pixelů a označí se kritéria, kterým se změnil verdikt nebo důkaz.

V detailu kroku se na změnu podíváte čtyřmi způsoby: Vedle sebe, Rozdíl, Posuvník (táhnete čáru přes oba screenshoty) a Prolnutí (jeden přechází do druhého). Klávesa G ukáže jeden krok ve všech jazycích a velikostech obrazovky najednou.

Stejné porovnání jako text, pro agenta nebo poznámky k vydání:

npx kaloko compare                       # aktuální běh proti referenci, jinak proti předchozímu běhu
npx kaloko compare --run <id> --baseline <id> --json

Ignorujte, co se mění pořád #

Hodiny, reklamy, karusely a „před 3 minutami“ se mění při každém běhu a skutečné rozdíly v nich zapadnou. Vynechte je z porovnání pixelů pomocí ignore: u kroku:

nodes:
  - id: home
    ignore:
      - { selector: ".ticker", note: živé ceny }
      - { rect: [0, 620, 1280, 180], viewport: desktop }

Hledat je ručně nemusíte:

npx kaloko walk --stability 3      # tři screenshoty každého snímku krátce po sobě
npx kaloko stability               # co se pohnulo, ve srovnání s dřívějšími běhy scénáře
npx kaloko stability --apply       # zapíše návrhy do ignore:

Než návrhy použijete, podívejte se na screenshoty: oblast, která se změnila, protože se opravdu změnila stránka, není šum.

Šum mohou označit i kontrolující. V detailu kroku na kaloko.app zvolí Označit proměnlivou oblast a nakreslí na screenshot obdélník. Ten se pak čárkovaně ukáže u každého běhu flow a rozdíl na plachtě ho hned vynechá. Do scénáře tyto oblasti dostanete příkazem:

npx kaloko stability --pull

Dotčené kroky pak projděte znovu: snímek si zapamatuje, které oblasti vynechal.

Kontrolovat stránky podle plánu (hostované běhy)

Marketingový web se mění několikrát týdně a nic z toho neprochází vašimi pull requesty. Hostovaný běh otevře stránky scénáře jen pro čtení v prohlížečích Kaloka každý den nebo týden, pořídí screenshoty celých stránek ve všech jazycích a velikostech obrazovky, zkontroluje, co se dá ze stránky přečíst, a nasdílí běh pod vaším jménem. CLI nemusí nikdo spouštět. Hostované běhy patří k plánu Business (2 000 načtených stránek měsíčně) a Enterprise (10 000).

1. Připravte scénář jen pro čtení #

Kroky scénáře otevírají stránky. Začít můžete přímo od stránek:

npx kaloko draft https://example.com/ https://example.com/pricing

2. Naplánujte ho #

npx kaloko schedule add --scenario qa/flows/public.yml --env production --every day --at 5
npx kaloko schedule add --scenario qa/flows/public.yml --env production --every week --weekday mon

--at je hodina v UTC. --every manual vytvoří plán, který poběží, jen když ho spustíte.

Fungují i stránky za přihlášením. Přihlašovací údaje HTTP Basic z prostředí se pošlou jednou a uloží zašifrované. Pro stránky přihlášeného uživatele si člověk uloží relaci přes npx kaloko auth save --env production --account member a plán ji použije s --account member.

3. Spravujte ho #

npx kaloko schedule list            # příští a poslední běh, stránky využité tento měsíc
npx kaloko schedule run <id>        # spustit hned
npx kaloko schedule pause <id>
npx kaloko schedule resume <id>
npx kaloko schedule remove <id>

Stejné plány najdete na kaloko.app v Nastavení → Integrace.

Přečtěte si výsledek #

Běh se objeví mezi ostatními, porovnaný s referencí scénáře, se stejnou plachtou, komentáři i schvalováním. Kontroly selektorů, textů, titulků a meta tagů se vyhodnotí. Kritéria, která potřebují plný průchod, zůstanou „nehodnoceno“ i s důvodem.

Co hostované běhy neumějí #

Stránky jen otevřou a přečtou. Nic neklikají, nepíšou, neodesílají ani nevytvářejí, takže kroky, které dělají víc než otevření stránky, vynechají a vyjmenují. Plný průchod potřebují i nativní aplikace, místní nebo neveřejné adresy, přihlašovací údaje posílané v hlavičkách a různé základní adresy pro jednotlivé jazyky.

Pro ně plán vyexportujte jako workflow pro GitHub Actions, které scénář projde s plným CLI:

npx kaloko schedule export github --scenario qa/flows/checkout.yml --env staging --every week

Workflow vypíše, které tajné proměnné potřebuje.

Jak se stránky počítají #

Počítá se každá načtená stránka: každý krok v každém jazyce a velikosti obrazovky. Scénář s 10 stránkami ve 2 jazycích na desktopu a mobilu načte za jeden běh 40 stránek, takže denní běh spotřebuje zhruba 1 200 stránek měsíčně.

Pozvat lidi a hosty

Běh k něčemu je, až když ho uvidí ti, kdo rozhodují. Přiveďte kolegy do organizace, pozvěte klienta do jednoho projektu, nebo nechte číst každého z firemní domény. Vieweři jsou v každém plánu zdarma, takže nemusíte šetřit tím, kdo se smí dívat.

Pozvěte kolegu do organizace #

1. Otevřete Nastavení → Lidé a zvolte Pozvat do organizace.

   

2. Zadejte e-mail a vyberte roli. Viewer čte, komentuje a schvaluje; ostatní role popisuje stránka Role a API tokeny.
3. Člověk dostane e-mail s odkazem a přes něj se k organizaci připojí.

Seznam v Nastavení ukazuje každého člena s rolí a s tím, kdy byl naposledy vidět, a nepřijaté pozvánky s tím, kdo je poslal a kdy vyprší.

Pozvěte někoho do jednoho projektu #

Klienti, externisté i kolegové z jiných týmů často potřebují jeden projekt, ne celou organizaci.

1. Otevřete projekt a zvolte Sdílet.
2. Napište e-mailovou adresu, klidně i mimo vaši organizaci, a vyberte roli.
3. Zvolte Pozvat. Pozvánka platí 14 dní.

Adresa mimo organizaci přijde jako host. Host vidí jen projekty, do kterých byl pozván: ne ostatní projekty, ne lidi z organizace, ne nastavení ani fakturaci. Dialog Sdílet také ukáže, kdo už přístup má a jestli je projekt otevřený všem členům, nebo omezený jen na uvedené lidi.

V plánu Business můžete hostovi nastavit datum, kdy přístup skončí; ten den projekt opustí a přijde mu e-mail. Hosté s rolí designer nebo vývojář / tester patří k plánu Enterprise; v ostatních plánech je host viewer.

Pusťte dovnitř firemní doménu #

Místo zvaní kolegů po jednom přidejte firemní doménu v Nastavení → Lidé → Domény pro přihlášení. Kontrolu nad ní prokážete TXT záznamem, který Kaloko ukáže; dokud doména není ověřená, nikdo se přes ni nepřipojí. Pak se každý s e-mailem na ověřené doméně přihlásí s výchozí rolí domény (viewer, pokud nezvolíte jinou). Domény veřejných schránek, třeba gmail.com, si přivlastnit nejde.

Čtenáři z vaší domény #

V plánu Business přepínač Čtenáři z naší domény na stejném místě pustí každého, kdo se přihlásí z ověřené domény, ke changelogu a dokumentaci všech produktů, i když je projekt omezený. Vstoupí jako vieweři a místo nezabírají. Víc na stránce Publikovat changelog s obrázky.

Kdo zabírá místo #

Vieweři nikdy. Designer, vývojář / tester a admin zabírají jedno místo, jednou za celou organizaci, ať jsou to členové, nebo hosté. Pozvánka s takovou rolí drží místo, dokud ji člověk nepřijme nebo ji nezrušíte.

Role a API tokeny

Každý člověk v organizaci má roli a každý token jedná za člověka, nikdy s většími právy, než ta role dovolí. Agenti a CI používají tokeny; místo v plánu nezabírají.

Role #

Projekt může mít vlastního admina projektu, který do projektu zve lidi, mění jim role a projekt může omezit nebo otevřít. Projekty zakládají vývojáři / testeři a admini; kdo projekt založí, stane se jeho adminem. Roli člena změníte v Nastavení → Lidé.

Vytvořte token v aplikaci #

1. Otevřete Nastavení → API tokeny.

   

2. Pojmenujte token podle toho, kde bude žít, třeba „CLI na notebooku“ nebo „GitHub Actions“.
3. Zaškrtněte, co smí. Číst může vždycky.
   • komentáře a schvalování: komentáře a verdikty vaším jménem
   • design: kaloko sync designových konceptů
   • nahrávání běhů: kaloko share z CLI nebo z CI
   • vše, co dovolí moje role
4. Vyberte, jak dlouho platí: 30 dní, 90 dní nebo rok.
5. Volitelně ho omezte na vybrané projekty; pak vidí jen ty a nové nezaloží.
6. Token jednou zkopírujte a uložte do .env projektu jako KALOKO_TOKEN.

Seznam ukazuje u každého tokenu vlastníka, roli, prefix, poslední použití a platnost. Zneplatnit token ukončí okamžitě.

Přihlaste se z terminálu #

Na vlastním počítači to jde rychleji:

npx kaloko login

Otevře se prohlížeč, kde kód schválíte, vyberete organizaci a to, co token smí. Token platí nejvýš 30 dní a uloží se do ~/.config/kaloko/.env. S --print ho jen vypíše, s --no-open ukáže odkaz bez otevření prohlížeče.

Tokeny pro CI #

Vytvořte token s rozsahem nahrávání běhů, nejlépe omezený na projekt, a uložte ho v CI jako secret KALOKO_TOKEN. npx kaloko ci github a ci gitlab napíšou workflow, které ho čte; víc v referenci CLI.

Pravidla, která nastaví admin #

V Nastavení → Zabezpečení může admin povolit tokeny se všemi právy jen adminům, vypnout tokeny omezené na projekty a rozhodnout, jestli si tokeny smějí vytvářet hosté. Token hosta vidí jen jeho projekty. V plánu Enterprise drží tokeny pro automatizaci, která nepatří žádnému člověku, servisní účty.

Nastavit firemní přihlášení

Pro adminy organizace. Kaloko se přizpůsobí přihlášení, které ve firmě už máte: osobní přihlášení v každém plánu, povinný druhý krok pro celou organizaci od plánu Business a vašeho poskytovatele identit se SCIM v plánu Enterprise.

Přihlášení v každém plánu #

Lidé se přihlašují jednorázovým odkazem z e-mailu, nebo přes Google, Microsoft či GitHub. Každý si v nastavení účtu může přidat passkey nebo autentizační aplikaci jako druhý krok.

V plánu Business může admin v Nastavení → Zabezpečení vyžadovat druhý krok po celé organizaci a nastavit limity relací. Kdo druhý krok nemá, musí si ho přidat, než bude pokračovat.

Nejdřív ověřte doménu #

Firemní přihlášení i SCIM se týkají jen adres z ověřených domén.

1. Otevřete Nastavení → Lidé a přidejte doménu v části Domény pro přihlášení.
2. Přidejte do DNS záznam TXT, který Kaloko ukáže, nebo doménu prokažte přihlášením přes Google Workspace či Microsoft 365.
3. Stiskněte Ověřit. Dokud doména není ověřená, nikdo se přes ni nepřipojí.

Připojte poskytovatele identit (Enterprise) #

1. Otevřete Nastavení → Zabezpečení → Firemní přihlášení.
2. Zvolte SAML (Okta, Entra ID, Google Workspace a další) a vložte metadata poskytovatele, nebo OIDC s issuerem, client ID a secretem. Metadata Kaloka i s certifikátem najdete na stejné stránce.
3. Stiskněte Vyzkoušet přihlášení. Ukáže, co poskytovatel poslal a jestli by to Kaloko přijalo; test nikoho nepřihlásí.
4. Přihlášení vynuťte. Lidé z ověřených domén se pak přihlašují jen přes vašeho poskytovatele. Admini s passkey nebo autentizační aplikací mají cestu dovnitř i v den, kdy poskytovatel nefunguje.

Další volby na stejné stránce:

• Šifrované assertion: vytvořte pár klíčů organizace; nový pár nechá starý fungovat, dokud ho neodeberete.
• Jednotné odhlášení: odhlášení u poskytovatele odhlásí i z Kaloka a naopak.
• Přihlášení z dlaždice aplikace u poskytovatele, vypnuté, dokud ho nezapnete, s výchozí stránkou, kam lidé přijdou.
• Druhý krok u vašeho poskytovatele může Kaloko uznat jako svůj, pro přihlášení přes vašeho poskytovatele.

Hosté z jiných firem se přihlašují jako dřív a vidí jen projekty, do kterých byli pozváni.

Zřizujte lidi přes SCIM (Enterprise) #

Základní adresu SCIM a token z Nastavení vložte do Okty nebo Entra ID. Přiřazení lidé přibudou s výchozí rolí své domény, skupiny se mapují na projekty a role a odebrání člověka ukončí jeho relace, zneplatní jeho tokeny a vyřadí ho ze všech projektů. Admina SCIM nikdy nevytvoří.

Omezte, odkud se lidé připojují (Enterprise) #

V Nastavení → Zabezpečení povolíte rozsahy IP adres pro aplikaci a zvlášť pro API, CLI a MCP. Audit log může proudit na podepsaný webhook, do Splunku nebo na endpoint kompatibilní s Datadogem.

Kde jsou vaše data a kdo je zpracovává: Bezpečnost a data.

Publikovat changelog s obrázky

Vaše přijaté běhy už obsahují každou obrazovku vydání. Kaloko z CHANGELOG.md ve vašem repozitáři udělá stránku s obrázky před a po, kterou si přečtou klienti, podpora i marketing. Takhle vzniká i changelog samotného Kaloka a je veřejný: kaloko.app/p/sinfin/kaloko/changelog.

Jednou to nastavte #

npx kaloko init --docs=changelog

Přidá CHANGELOG.md (Keep a Changelog) a blok changelogu do kaloko.config.yml. Repozitář s několika aplikacemi je vypíše pod products:; npx kaloko products sync je dá do Kaloka ještě před prvním vydáním.

Dejte do záznamu obrázky #

Obrázek odkazuje na krok místo na soubor:

- Ceník srovnává všechny plány v jedné tabulce.
  ![Předtím](kaloko:KALOKO-public/pricing?version=prev) ![Potom](kaloko:KALOKO-public/pricing)

KALOKO-public je id scénáře a pricing id kroku. Bez ?version= odkaz ukáže nejnovější přijatou obrazovku; ?version=prev tu z předchozího vydání.

Připravte koncept záznamu #

npx kaloko changelog draft            # vypíše záznam Unreleased
npx kaloko changelog draft --apply    # zapíše ho do CHANGELOG.md

Koncept posbírá pull requesty a commity od posledního vydání, roztřídí je do Added, Changed, Fixed a Removed a přidá obrázky před a po u obrazovek, které přijaté běhy ukazují jinak. Řádky pak přepište pro lidi: co teď můžou udělat, jedna změna na řádek. --since <tag> začne od jiného vydání.

Zapište vydání #

npx kaloko release 2.4.0

Z Unreleased se stane 2.4.0, vydání se zapíše i s přijatými běhy, které dávají obrázky, a příkaz vypíše adresu stránky. Bez čísla verze si ji Kaloko přečte z gitových tagů, package.json, release-please nebo changesets.

Když vydání dělá release-please, changesets nebo semantic-release, píše CHANGELOG.md dál ten nástroj a Kaloko ho jen čte. npx kaloko ci github --release přidá workflow, které zapíše každé zveřejněné vydání na GitHubu.

Kdo ho čte #

Changelog najdete v aplikaci pod Produkty. Čte ho každý, kdo vidí některý z projektů produktu, i hosté. V plánech Business a Enterprise může admin těch projektů přímo na stránce zvolit, kdo ho čte dál:

• Čtenáři z naší domény: každý, kdo se přihlásí z ověřené domény vaší organizace.
• Kdokoli s odkazem: veřejná stránka s odběrem Atom. Vyhledávače ji indexují, jen když to povolíte.

Čtenáři si na stránce changelogu můžou zapnout i e-mail „Co je nového“ (od plánu Business): každé nové vydání jim přijde s obrázky v jejich jazyce.

Jak stránku používají čtenáři: Co je nového. Návody stejně aktuální udržíte podle stránky Publikovat živou dokumentaci.

Publikovat živou dokumentaci a hlídat zastaralé části

Návody ve vašem repozitáři můžou místo vložených screenshotů ukazovat obrazovky z přijatých běhů, takže obrázky nikdy nezestárnou. Když se obrazovka po napsání textu změní, Kaloko řekne, kterou část zkontrolovat. Stránky, které právě čtete, vznikají přesně takhle: kaloko.app/p/sinfin/kaloko/docs.

Připravte složku #

npx kaloko init --docs=full

Vytvoří docs/ se čtyřmi složkami podle Diátaxis, v každé šablonu:

index.md je úvodní stránka. Front matter je nepovinný: title (jinak první nadpis) a order (pořadí v postranním menu). Stránky propojujte relativními odkazy na .md.

Napište stránku #

Obrázky jsou odkazy na kroky, stejně jako v changelogu:

1. V horní liště zvolte **Přihlásit**.
   ![Přihlašovací stránka](kaloko:KALOKO-public/login)

Překlad leží vedle originálu: pay.cs.md vedle pay.md, jazyky vyjmenuje konfigurace (docs.languages: [en, cs], jazyk originálů první). Obrázky se řídí jazykem textu.

Když má každá položka seznamu jednu akci a obrázek hned pod sebou, dá se stránka projít i jako průvodce: čtenář zvolí Projít krok za krokem, vidí vždy jeden krok a může si odškrtnout Mám vyzkoušeno.

Publikujte #

npx kaloko docs publish                     # dokumentace pro latest
npx kaloko docs publish --version 2.4.0     # dokumentace vydání (Business)

Čtenáři dostanou výběr verze, přepínač jazyka a obrazovky a hledání a každý obrázek otevře svůj krok na plachtě. kaloko release publikuje složku s dokumentací pro svou verzi sám, pokud nepřidáte --no-docs. Kdo dokumentaci čte, se řídí stejnými pravidly jako changelog: viz Publikovat changelog s obrázky.

Hlídejte zastaralé části #

Při publikování si Kaloko zapamatuje obrazovku za každým odkazem. Když pozdější přijatý běh ukáže jinou obrazovku, uvidí lidé, kteří dokumentaci píšou, u části poznámku „Obrazovka se změnila ve verzi 2.4 — zkontrolujte text.“ (Business).

npx kaloko docs check             # proti publikované dokumentaci; potřebuje token
npx kaloko docs check --offline   # jen lokální soubory

Chyby: rozbité odkazy, kroky, které scénáře nemají, odkazy bez přijatého obrázku a zastaralé části. Varování: chybějící nebo neaktuální překlady a položky changelogu, které lidé uvidí, ale nemají obrázek. Při chybě příkaz skončí kódem 1; s --strict i při varování, což se hodí do CI.

U každé zastaralé části otevřete krok, porovnejte ho s textem a přepište, co už nesedí; poznámka zmizí při dalším kaloko docs publish. Pokud text pořád sedí, kaloko docs publish --reviewed poznámky smaže beze změny textu. Použijte ho, až když jste je přečetli.

Jak dokumentaci dostat ven jako soubory pro jiný web: Exportovat dokumentaci a changelog.

Exportovat dokumentaci a changelog

Váš web s dokumentací už možná má vlastní build, nebo klient chce návod jako PDF. kaloko export zapíše dokumentaci i changelog s obrázky jako obyčejné soubory, takže nic nezůstane zamčené v Kaloku.

Vyberte formát #

npx kaloko export --format docusaurus --out website/docs

Z odkazů na kroky se stanou obyčejné obrázky v jazyce a velikosti obrazovky exportu.

Vyberte, co do exportu patří #

• --what docs nebo --what changelog vyexportuje jen jedno z nich; výchozí jsou obě.
• --version 2.4.0 vyexportuje dokumentaci vydání místo té nejnovější.
• --lang cs vyexportuje jeden jazyk.
• --product shop vybere produkt, když jich konfigurace má víc.
• --out určí složku nebo soubor, kam se export zapíše.

Publikované, nebo lokální #

Bez dalších voleb export vezme to, co jste publikovali přes kaloko docs publish. S --local vezme soubory ve vašem repozitáři, aniž by je publikoval. Hodí se to, když chcete změnu zkontrolovat dřív, než půjde ven.

Udržujte web s dokumentací v souladu #

Existující web si nechá vlastní build. Buď do jeho složky vyexportujete a výsledek commitnete, nebo export spustíte v jeho CI před buildem:

npx kaloko export --format vitepress --what docs --out docs-site/guide

Token v CI potřebuje jen čtení; viz Role a API tokeny.

Stáhněte export ze stránky dokumentace #

Čtenáři, kterým vyhovuje soubor, použijí Stáhnout na stránce dokumentace nebo changelogu. Nabídne stejné formáty; v plánech pod Business jsou i tam jen Markdown a JSON.

Každý export se otevře i bez Kaloka. Odkud stránky pocházejí a jak je držet aktuální, popisuje Publikovat živou dokumentaci a hlídat zastaralé části.

Příkazy CLI

Všechny příkazy CLI kaloko a co dělají. Spouštějí se jako npx kaloko <příkaz> v projektu, který má balíček nainstalovaný. npx kaloko help vypíše stejný seznam se všemi volbami.

Volby, které fungují všude: --run <id|složka> (nebo KALOKO_RUN) vybere běh, --config <soubor> konfiguraci a KALOKO_AGENT=<jméno> označí, co zapsal agent.

Nastavení projektu #

Průchod a snímání #

Výsledky a kontrola #

Sdílené běhy #

Jira, Linear a hostované běhy #

Produkty, changelog a dokumentace #

Design #

kaloko help vypíše všechno výše se všemi volbami.

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íče kroku (nodes) #

Každý krok potřebuje id, kind a title.

Kritéria #

Každé kritérium má id (AC1, AC12b), text pro lidi, volitelně highlight (CSS selektor, který se na screenshotu orámuje) a právě jednu kontrolu check: deterministic, semantic nebo manual. Všechny typy kontrol a jejich volby najdete v Kritéria, kontroly a packy.

Šipky (edges) #

Snímky (capture) #

capture kroku má přednost před scénářem a scénář před konfigurací.

Kritéria, kontroly a packy

Kritérium je jedna věc, kterou má krok splnit. Má id (AC1), text pro lidi a právě jednu kontrolu check. Jak je do scénáře přidat: Přidat kritéria a packy. Jak se z výsledků stane verdikt: Jak vznikají verdikty.

Druhy kontrol #

Čísla, data a počty patří do deterministických kontrol, nikdy do sémantické otázky. V jedné otázce se ptejte na jednu věc.

Deterministické kontroly (assert) #

Společné volby: selector (CSS), pattern (regulární výraz) s flags (i, m, s), value, min, max, all (vyhovět musí každá shoda, ne jen jedna).

Obsah stránky #

Adresa, metadata a odkazy #

Styly a hodnoty ve stránce #

Přístupnost (používá je pack a11y) #

Výkon, aplikace a design #

Packy #

packs: [seo, a11y] u kroku přidá pevnou sadu kritérií. Vlastní kritérium se stejným id nahradí kritérium z packu; tak se mění limit (AC401 s max: 4000).

Pack a11y pokrývá část WCAG 2.2 AA. Audit se čtečkou obrazovky nenahradí.

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
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ě #

Prostředí #

Každý klíč pod environments je název, který použijete v kaloko start --env.

Evaluátory #

Dokumentace a produkty #

Bez products je produktem projekt.

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.

Nástroje MCP

MCP server Kaloka dovolí agentovi číst běhy, připomínky, návrhy, changelog i dokumentaci a odpovídat kontrolujícím. Je součástí plánu Team a vyšších. Zachytávání, vyhodnocení a nahrávání zůstávají v CLI.

Připojení #

Server je na https://kaloko.app/mcp (MCP přes Streamable HTTP). Ověříte se API tokenem organizace v hlavičce Authorization; jak ho vytvořit: Role a tokeny.

claude mcp add --transport http kaloko https://kaloko.app/mcp --header "Authorization: Bearer $KALOKO_TOKEN"

Ostatní agenti (Codex, Cursor) dostanou stejnou adresu a hlavičku jako HTTP MCP server. Na čtení stačí token jen pro čtení; nástroje, které zapisují, potřebují token s příslušným rozsahem. Screenshoty a soubory přes MCP necestují: odpovědi nesou jejich adresy, které stáhnete stejným tokenem.

Běhy a kontrola #

Připomínky a úkoly #

Design #

Obrazovky, changelog, dokumentace a produkty #

Chyby se vracejí jako výsledek nástroje označený jako chyba (neznámý běh, chybějící argument). Neplatný token dostane HTTP 401; organizace v plánu nižším než Team se dozví, že MCP server její plán nemá.

Jak Kaloko odpovídá vašim aplikacím

Jeden repozitář je málokdy jedna aplikace. V monorepu bývá aplikací několik, jedna aplikace se táhne přes víc repozitářů, agentura má projekt pro každého klienta a každý tým pojmenovává prostředí jinak. Kaloko proto pracuje s několika pojmy, které jednou přiřadíte ke své situaci.

Pojmy #

Produkty jsou volitelné #

Bez produktů je produktem projekt a jeho changelog je changelog projektu. Tak začíná většina týmů. Až budete potřebovat víc, vypište produkty pod products: v kaloko.config.yml a scénáře uvedou svůj přes product: a module:. Nic se nemusí přesouvat.

Projekt může pokrývat několik produktů a na jednom produktu může pracovat víc projektů. Dokumentace a záznamy v changelogu odkazují na kroky, takže produkt a modul znají ze scénáře.

Verze patří produktům #

Prostředí jen říká, kde běh proběhl. Běh je svázaný s verzí produktu a dokumentace pro verzi 2.4 ukazuje přijaté běhy verze 2.4. Obrázky pocházejí z prostředí, které produkt určí jako referenční (reference_env), třeba staging u interního nástroje nebo production-cz u portálu jen pro Česko.

Čtyři obvyklá uspořádání #

1. Jedna aplikace, jeden tým. Žádné produkty; projekt je aplikace a má jeden changelog. To je výchozí stav.
2. Monorepo s několika aplikacemi. Produkt pro každou aplikaci; projekty podle týmů nebo aplikací.
3. Agentura. Projekt pro každého klienta a produkt pro každou dodávku. Hosté od klienta čtou jen changelog a dokumentaci svého produktu.
4. Velká aplikace s moduly. Jeden produkt s moduly podle týmů. Každý tým se stará o dokumentaci svého modulu a release má jeden společný changelog se sekcí pro každý modul.

kaloko init navrhne produkt pro každou aplikaci ve složce apps/, která má vlastní package.json. kaloko products sync je pošle do Kaloka ještě před prvním vydáním a Produkty v menu aplikace ukážou každý produkt, který čtete.

Každá část funguje sama #

Můžete používat jen changelog, jen dokumentaci, jen dokumentaci jednoho modulu, jen obrázky pro web s dokumentací, který už máte (kaloko export), nebo jen e‑mail „Co je nového“. Nic nevyžaduje celou sadu.

Jak vznikají verdikty

Každé kritérium na plachtě skončí jako splněno, částečně, nesplněno, nebo čeká na člověka. Rozhodují o tom tři druhy soudců v pevném pořadí: kontroly, které počítají, AI evaluátor na to, co chce úsudek, a lidé, kteří mají poslední slovo.

Nejdřív kontroly, které počítají #

Co jde změřit, se zkontroluje přímo na živé stránce při zachycení kroku: je tam text, pole má popisek, adresa po kroku sedí, barva odpovídá tokenu z designu, stránka se načte v časovém limitu. Ke každému výsledku zůstane důkaz, třeba prvek, který odpovídal, nebo naměřená hodnota, takže vidíte, proč kontrola prošla nebo neprošla. Tyto kontroly běží bez AI a nikdy nespotřebují žádný dotaz na evaluátor.

Evaluátor na úsudek #

Kritéria jako „chybová hláška říká, co má člověk udělat“ jdou sémantickému evaluátoru. Výchozí je JEV od TypeSafe. Čte zredukovanou osnovu stránky, ne screenshot, a vrátí skóre mezi 0 a 1. Nad prahem pro splnění (výchozí 0,85) je kritérium splněné, pod prahem pro nesplnění (0,15) nesplněné a mezi nimi čeká, až rozhodne člověk. Prahy nastavíte v kaloko.config.yml.

Kritéria označená vision: true a odpovědi v nejistém pásmu dostanou druhý pohled od evaluátoru, který vidí screenshot. Ten navíc jednou větou řekne, co rozhodlo; na plachtě ji najdete jako „Proč“.

Evaluátor běží s vaším vlastním klíčem v každém plánu, nebo přes Kaloko od plánu Team v rámci měsíčního počtu dotazů. Odpovědi se ukládají, takže nezměněnou obrazovku vyhodnotíte znovu bez nového dotazu. Bez klíče i hostované evaluace zůstanou tato kritéria „nehodnoceno“, dokud nerozhodne kontrolující. kaloko calibrate porovná evaluátor s verdikty vašich kontrolujících a navrhne prahy.

Rozhodují lidé #

Kontrolující krok schválí, vrátí s poznámkou, nebo rozhodne kritérium, kterým si evaluátor nebyl jistý. Nakonec celý běh přijme nebo vrátí. Každé rozhodnutí nese jméno.

• Povinní schvalovatelé (od plánu Team): běh je přijatý, až ho určení lidé schválí.
• Schválení zůstává. Když se nasdílí nový běh, krok, jehož screenshoty a kritéria se od posledního přijatého běhu nezměnily a jehož kontroly pořád procházejí, si ponechá schválení, které mu dal člověk, i s tím, kdo a kdy. V režimu kontroly čeká jen zbytek. Převzaté schválení může kdokoli zrušit. Převzaté schválení nikdy běh nepřijme a nepočítá se za povinné schvalovatele.
• Agenti za lidi neschvalují. Rozhodnutí agenta nebo tokenu jsou označená jako jejich a za rozhodnutí člověka se nepočítají.

Proč v tomhle pořadí #

Počítání je levné a přesné, proto jde první. Úsudek je drahý a občas se mýlí, proto řeší jen to, co spočítat nejde, a řekne, když si není jistý. Lidé vidí u každého verdiktu důkaz i důvod a za přijetí se zapíše jejich rozhodnutí.

Bezpečnost a vaše data

Kaloko běží tam, kde je váš kód a váš agent: CLI prochází, zachycuje a kontroluje na vašem počítači nebo ve vašem CI. Služba na kaloko.app ukládá to, co nasdílíte, zobrazuje plachtu a sbírá rozhodnutí. Tahle stránka vysvětluje, co kam putuje. Kde jsou data uložená a které firmy je zpracovávají, najdete na stránce o důvěře a bezpečnosti, kterou průběžně aktualizujeme.

Co opouští váš počítač #

Dokud nesdílíte, nic. kaloko walk, evaluate a preview pracují lokálně a místní plachta se otevře z disku. kaloko share nahraje běh: screenshoty, zachycené HTML, kritéria s důkazy a videa tam, kde je váš plán uchovává. Soubory se posílají podle otisku obsahu, takže zachycení, které se nezměnilo, se znovu neposílá.

Co vidí evaluátor #

U textových kritérií dostane evaluátor zredukovanou osnovu stránky se zamaskovanými e‑maily a tokeny, surové HTML nikdy. Screenshot jde evaluátoru na obrázky jen u kritérií označených vision: true a u odpovědí, kterými si textový evaluátor nebyl jistý. S vlastním klíčem jde požadavek z vašeho počítače přímo k danému poskytovateli, bez něj přes Kaloko.

Tajné údaje zůstávají venku #

Tajné údaje se do kaloko.config.yml nikdy nepíšou. Konfigurace jen pojmenuje proměnnou prostředí podle vašeho výběru (password_env: STAGING_PASSWORD) a hodnota se načte z prostředí, z .env projektu nebo z ~/.config/kaloko/.env. Hodnoty těchto proměnných se ze zachyceného HTML, textu stránky i výstupu konzole odstraní dřív, než se cokoli uloží. Přihlášení uložená přes kaloko auth save zůstávají na vašem počítači a nikdy se nenahrávají.

Produkce jen pro čtení #

Prostředí označené jako produkce je v CLI vždy jen pro čtení: veřejné stránky jako návštěvník, žádné přihlašování do administrací, žádná vytvořená data. Aby tam scénář mohl běžet, musí uvést readonly: true.

Běhy vyprší #

Každý sdílený běh má datum expirace, výchozí je 30 dní a nejvýš retence vašeho plánu, a potom se smaže. kaloko keep běh ponechá natrvalo; v plánech Business a Enterprise přijaté běhy nevyprší, dokud plán trvá. Od plánu Team si běh můžete kdykoli stáhnout jako ZIP přes kaloko export.

Jak se servírují soubory #

Nahrané soubory se servírují z oddělené domény přes krátkodobě podepsané odkazy. Zachycené HTML se ukazuje v sandboxu bez skriptů.

Kdo se dostane dovnitř #

Lidé se přihlašují jednorázovým odkazem z e‑mailu nebo přes Google, Microsoft či GitHub a jako druhý krok si můžou přidat passkey nebo autentizační aplikaci. Enterprise přidává firemní přihlášení přes SAML nebo OIDC a SCIM.

Co člověk smí, určuje role: viewer čte, komentuje, schvaluje a vrací; designer a vývojář / tester navíc nahrávají; admin navíc spravuje členy, tokeny a nastavení. Vieweři jsou v každém plánu zdarma. API tokeny mají vlastní rozsah a platnost a token, který CLI dostane přes kaloko login, platí nejvýš 30 dní.

Na co se ptá bezpečnostní prověrka #

Stránka o důvěře a bezpečnosti odpovídá, kde jsou data, jak jsou šifrovaná, kdo je zpracovává a jak daleko je příprava na SOC 2. Kvůli nahlášení zranitelnosti nebo smlouvě o zpracování osobních údajů napište na kontakt, který tam najdete.

Co je nového