Dokumentace

Kaloko

Stáhnout
Markdown s obrázky (.zip)Složka pro Docusaurus (.zip)Složka pro VitePress (.zip)Složka pro MkDocs (.zip)HTML pro offline čtení (.zip)PDFNovinky jako JSON
Stránky

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, i s dalším spuštěním a s tím, kolik výsledků kondice poslední běh našel nových a opravených.

Spustit po nasazení

Plán se může spustit i ve chvíli, kdy se web nasadí. Vytvořte mu adresu pro spuštění a tajemství:

npx kaloko schedule hook <id>      # vypíše adresu a tajemství, jen jednou

nebo v Nastavení → Integrace → Běhy na serveru Kaloka → Spustit po nasazení. Tajemství uložte do tajných proměnných CI nebo hostingu, nikdy do repozitáře. Další volání příkazu vytvoří nové tajemství a to staré přestane platit; --remove spouštění odebere.

Každé volání s tajemstvím spustí běh v nejbližší čtvrthodině. Volání, která přijdou, než běh začne, jsou jeden běh; volání během průchodu dostane vlastní běh po něm. Jeden plán přijme nejvýš 30 volání za hodinu a každé je v auditním logu.

Z jakéhokoli jobu v CI, po kroku s nasazením:

curl -fsS -X POST "$KALOKO_HOOK_URL" -H "Authorization: Bearer $KALOKO_HOOK_SECRET"

Vercel. Vercel hlásí každé nasazení do GitHubu, takže krátké workflow zavolá spouštění, jakmile je produkce nahoře. Přidejte do repozitáře tajné proměnné KALOKO_HOOK_URL a KALOKO_HOOK_SECRET a commitněte .github/workflows/kaloko-after-deploy.yml:

name: Kaloko after deploy
on: deployment_status
jobs:
  kaloko:
    if: github.event.deployment_status.state == 'success' && github.event.deployment.environment == 'Production'
    runs-on: ubuntu-latest
    steps:
      - run: curl -fsS -X POST "$KALOKO_HOOK_URL" -H "Authorization: Bearer $KALOKO_HOOK_SECRET"
        env:
          KALOKO_HOOK_URL: ${{ secrets.KALOKO_HOOK_URL }}
          KALOKO_HOOK_SECRET: ${{ secrets.KALOKO_HOOK_SECRET }}

Netlify. Site configuration → Notifications → Deploy notifications → Add notification → Outgoing webhook. Událost „Deploy succeeded“, jako URL adresa pro spuštění, tajemství jako „JWS secret token“. Kaloko podpis od Netlify ověří.

Vlastní odesílatel. Místo tokenu můžete podepsat tělo požadavku: pošlete X-Kaloko-Signature: sha256=<hex>, HMAC-SHA256 těla s tajemstvím jako klíčem.

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.

Kontroly z packů (SEO, přístupnost) patří do kondice běhu, ne do jeho verdiktu. Když má běh proti minulému novou chybu v kondici, plán to oznámí sledujícím scénáře, kanálům, které odebírají „Zhoršená kondice“, a webhooku health.worse. U každého plánu si vyberete, jestli hlásit nové chyby (výchozí), i nová varování, nebo nic: v Nastavení → Integrace → Běhy na serveru Kaloka, nebo volbou --health-alert error|warning|off u kaloko schedule add. Víc v návodu Kontrola kondice aplikace.

Stack kroky: mnoho stránek jedné šablony

Stack krok zastupuje celou rodinu stránek, třeba všechny produkty. Hostovaný běh vezme jeho stránky z items.urls, items.sitemap nebo items.robots (i zabalené sitemapy a indexy sitemap). match, exclude, limit a rotate: week fungují stejně jako v kaloko walk, takže oba ve stejném týdnu vyberou stejné stránky.

Každou stránku otevře jednou, v první velikosti obrazovky kroku, a přečte ji bez screenshotu. Kontroly, kterým stačí prvky stránky (selektory, texty, titulky, meta značky), rozhodne; indexová pole titulek, H1, popis, počet slov a typy JSON-LD vyplní; u všeho ostatního napíše „nevyhodnoceno“ i s důvodem. Stavový kód HTTP zůstane prázdný. Na plachtě je krok stack s indexem, stejně jako po průchodu.

Velký stack se čte během několika čtvrthodinových kol, v každém nejvýš 150 stránek. kaloko schedule list a Nastavení → Integrace ukazují, kolik už je přečteno, a běh se nasdílí, až jsou přečtené všechny stránky. Než doběhne, Spustit teď, spouštěč po nasazení i uložená změna počkají a přijdou na řadu po něm; pozastavení plánu ho ukončí. Jeden běh přečte nejvýš 1 000 stránek stacků a ze sitemap nejvýš 5 × limit vyhovujících adres pro každý jazyk (nejvýš 20 000). Když kolo selže nebo se nikam nedostane (server se sitemapou neodpovídá), další kolo to zkusí znovu; po třech takových kolech za sebou se běh vzdá a plán počká na další termín.

Sitemapy můžou ležet na jiném serveru, třeba na CDN. Kaloko je stahuje bez hesla a cookies prostředí, a jen když se jméno překládá na veřejné adresy, a to i po každém přesměrování. Stránky otevírá jen na adresách prostředí; ostatní ze sitemapy vynechá a napíše to. match a exclude můžou mít nejvýš 300 znaků, bez zpětných odkazů a lookaroundu.

Stack s items.variants: hreflang seskupí jazykové verze stránky stejně jako kaloko walk: seznam, výřez na tento týden i id se berou ze source_locale a v ostatních jazycích se otevře hreflang alternativa každé stránky. Před stránkami si běh u každé zdrojové stránky přečte hlavu stránky (<head>) kvůli hreflang. Každé takové čtení se počítá jako jedna stránka, do měsíčního limitu i do 150 stránek jednoho kola, takže stack se 100 produkty ve třech jazycích spotřebuje 400 stránek: 100 čtení a 300 stránek. Stránka bez překladu se v indexu stacku označí a započítá do HC1005, stejně jako po průchodu. Čtení zůstává na adresách prostředí, i po přesměrování, a nese tam heslo nebo cookies plánu, tytéž, které dostane hostovaný prohlížeč. Když hreflang míří na produkci a běh prochází staging, otevře se cesta každé alternativy na stagingové adrese daného jazyka. Když zdrojová stránka přesměruje mimo prostředí, běh za ní nejde: na rozdíl od kaloko walk ji nahlásí jako chybějící překlad (cannot read the page).

Jedna adresa pro každý jazyk

Když má prostředí base_url pro každý jazyk zvlášť, hostovaný běh ji vybere stejně jako kaloko walk: vlastní adresu jazyka, jinak default.

environments:
  production:
    base_url: { default: "https://www.example.com", cs: "https://www.example.cz/cs" }
    readonly: true

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 stack kroky, které berou stránky z crawl, script nebo file. Odkazy do CMS z items.resolve hostované běhy nevyplní.

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

Každá stránka stacku se počítá jednou, když se přečte. Týdenní stack se 100 stránkami ve 3 jazycích spotřebuje zhruba 1 300 stránek měsíčně. Když měsíční rozpočet dojde uprostřed stacku, běh až den počká, jestli nějaký přibude (nový měsíc, vyšší limit), pak nasdílí stránky přečtené do té doby a u ostatních napíše, že je nepřečetl.

Na této stránceNa této stránce