Fejlesztőknek

Akadálymentességi ellenőrzés a CI-ban

Vizsgálja meg minden előnézeti telepítés fő oldalait ugyanazzal a motorral, amely az éles webhelyét felügyeli, és állítsa meg azt a pull requestet, amely súlyos akadálymentességi hibát hozna be.

A Growth (havi 500 ellenőrzött oldal) és az Agency (2000) csomag része.

API-kulcs létrehozása Csomagok

Így működik

01
Hozzon létre kulcsot
Az irányítópult API és CI fülén. Mentse titkos változóként a CI-ban, például EQUALVIA_API_KEY néven.
02
Adjon hozzá egy lépést
Az előnézeti telepítés után futtassa a szkriptünket legfeljebb 10 oldal címével. Nincs függősége, Node 18 vagy újabb kell hozzá.
03
Megkapja az eredményt
A feladat a választott súlyosságú vagy annál rosszabb hibánál sikertelen lesz, és minden hibát felsorol az elemmel és a WCAG-kritériummal.

A CI beállítása

A szkript (/ci/equalvia-check.mjs) elindít egy ellenőrzést, megvárja az eredményt, és kiírja. GitHub Actionsben hibajelzéseket (annotation) és egy táblázatot is ad a futás összefoglalójához.

GitHub Actions: minden sikeres előnézeti telepítés után

# .github/workflows/accessibility.yml
name: Accessibility
on: deployment_status

jobs:
  equalvia:
    if: github.event.deployment_status.state == 'success'
    runs-on: ubuntu-latest
    steps:
      - name: EqualVia accessibility check
        env:
          EQUALVIA_API_KEY: ${{ secrets.EQUALVIA_API_KEY }}
          URL: ${{ github.event.deployment_status.target_url }}
        run: |
          curl -fsSL https://equalvia.com/ci/equalvia-check.mjs -o equalvia-check.mjs
          node equalvia-check.mjs "$URL/" "$URL/pricing" "$URL/contact" --fail-on serious

A Vercel, a Netlify és a legtöbb tárhely jelenti a GitHubnak az előnézeti telepítéseket, erre figyel a deployment_status esemény. Rögzített verziót szeretne? Töltse le egyszer a szkriptet, és tegye be a repositoryba, ahelyett hogy minden futásnál letöltené.

GitLab CI: a review appot telepítő feladat után

# .gitlab-ci.yml (after the job that deploys the review app)
accessibility:
  stage: test
  image: node:20
  variables:
    EQUALVIA_URLS: "$CI_ENVIRONMENT_URL/ $CI_ENVIRONMENT_URL/pricing"
  script:
    - curl -fsSL https://equalvia.com/ci/equalvia-check.mjs -o equalvia-check.mjs
    - node equalvia-check.mjs --fail-on serious

Bármely más CI (Bitbucket, CircleCI, Jenkins, Azure DevOps) ugyanígy működik: töltse le a szkriptet, és futtassa Node-dal.

A szkript kapcsolói

Kapcsoló	Mit csinál
`<url> …`	Az ellenőrzendő oldalak, legfeljebb 10. Vagy az EQUALVIA_URLS változóban (szóközzel elválasztva).
`--fail-on <szint>`	A legenyhébb súlyosság, amely megállítja a feladatot: critical, serious (alapértelmezett), moderate, minor vagy none (csak jelentés).
`--baseline <siteId>`	Csak azok a hibák számítanak, amelyek ennek a felügyelt webhelynek a legutóbbi vizsgálatában nincsenek benne. Lásd lent.
`--label <szöveg>`	Az irányítópult ellenőrzéslistájában jelenik meg. Alapértelmezés: a CI változóiból az ág és a commit.
`--locale <en\|hu>`	A hibák címének nyelve. Alapértelmezés: a fiókjáé.
`--timeout <másodperc>`	Meddig várjon az eredményre. Alapértelmezés: 300.
`--json`	Összefoglaló helyett a nyers eredményt írja ki JSON-ban.

Kilépési kódok

Kód	Jelentés
`0`	Sikeres.
`1`	Sikertelen: a küszöböt elérő hiba, vagy olyan oldal, amelyet nem tudtunk ellenőrizni.
`2`	Az ellenőrzés nem futott le: hiányzó vagy visszavont kulcs, csomag, elfogyott keret, hálózat.

Csak az új hibák

Ritkán indul hibátlanul egy webhely, és ha a CI-ellenőrzés minden futáskor elbukik, hamar kikapcsolják. Baseline-nal egy oldal hibáit a felügyelt webhely legutóbbi vizsgálatának ugyanazon oldalával vetjük össze (útvonal alapján, így az előnézeti cím megtalálja az éles párját), és csak azok számítanak, amelyek ott még nincsenek meg. A webhelyen figyelmen kívül hagyott szabályokat is kihagyjuk. A webhelyek azonosítóit az irányítópult API és CI fülén vagy a GET /api/v1/sites válaszában találja.

node equalvia-check.mjs "$URL/" "$URL/pricing" --fail-on serious --baseline SITE_ID

Jó tudni

Az oldalaknak elérhetőnek kell lenniük az internetről, mert a szervereink töltik be őket. Védett előnézetnél használjon nyilvános staging címet vagy a tárhely megkerülési lehetőségét (Vercelnél a protection-bypass lekérdezési paramétert; ilyenkor az URL az ellenőrzéssel együtt tárolódik).
Egy ellenőrzés minden URL-je egy oldalt használ fel a havi keretből, az eredménytől függetlenül. A keret minden hónap elején (UTC) újraindul.
Ha egy oldal nem töltődik be, hibakóddal válaszol vagy hibaoldalra irányít át, az ellenőrzés sikertelen: egy hibás telepítés soha ne menjen át.
Az ellenőrzések a felügyelettől külön futnak: nem változtatják a webhelyei jelentését, előzményeit és az e-mail-összefoglalókat.
Az automatikus vizsgálat az akadálymentességi hibák nagy részét megtalálja, de nem mindet. A kiadási rutinban maradjanak meg az irányított kézi ellenőrzések is.

REST API

A szkript egy kis REST API vékony burka. Az API-t bármiből hívhatja: saját szkriptből, hibajegykezelőből vagy belső irányítópultról.

Hitelesítés

A kulcsot az Authorization fejlécben küldje: Authorization: Bearer eqv_… Minden válasz JSON. A hibák így néznek ki: {"error": {"code": "…", "message": "…"}}.

Végpontok

Metódus	Útvonal	Mit ad vissza
`POST`	`/api/v1/checks`	Elindít egy ellenőrzést 1–10 URL-lel. 202-vel válaszol: a futó ellenőrzés és a kerete.
`GET`	`/api/v1/checks/{id}`	Egy ellenőrzés minden oldal hibáival. Kérdezze le néhány másodpercenként, amíg a status nem "running".
`GET`	`/api/v1/checks`	A 20 legutóbbi ellenőrzése, oldalankénti részletek nélkül.
`GET`	`/api/v1/sites`	Felügyelt webhelyei a legutóbbi vizsgálat hibaszámaival.
`GET`	`/api/v1/sites/{id}/issues`	Egy webhely legutóbbi vizsgálatának minden hibája: szabály, súlyosság, WCAG- és EN 301 549-hivatkozás, oldal, elem, HTML és javítási javaslat. ?locale=hu a magyar címekhez.
`GET`	`/api/v1/usage`	A hónapban felhasznált oldalak, a keret és az újraindulás ideje.

Ellenőrzés indítása

A POST /api/v1/checks törzse:

Mező	Jelentés
`urls`	Kötelező. 1–10 abszolút http(s) URL.
`failOn`	critical, serious (alapértelmezett), moderate, minor vagy none.
`baselineSiteId`	Nem kötelező. Az egyik felügyelt webhelye: csak az ott nem szereplő hibák számítanak.
`label`	Nem kötelező. Legfeljebb 120 karakter, például az ág és a commit.
`locale`	Nem kötelező. en vagy hu, a hibák címének nyelve.

curl -X POST https://equalvia.com/api/v1/checks \
  -H "Authorization: Bearer $EQUALVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://preview.example.com/"], "failOn": "serious"}'

curl https://equalvia.com/api/v1/checks/CHECK_ID \
  -H "Authorization: Bearer $EQUALVIA_API_KEY"

Az eredmény

A passed értéke null, amíg az ellenőrzés fut. A failing az eredményt eldöntő elemeket számolja (a failOn szintjén vagy felette, baseline-nal csak az újakat), a totals mindent, amit találtunk. Baseline-nal a newTotals, a hibák newCount mezője és az elemek new jelzője mutatja, mi új.

{
  "check": {
    "id": "cm1x8k2q40001",
    "status": "completed",
    "passed": false,
    "failOn": "serious",
    "baselineSiteId": null,
    "label": "feature/checkout @ 3f6e478",
    "pageCount": 1,
    "pagesWithErrors": 0,
    "totals": { "critical": 1, "serious": 2, "moderate": 0, "minor": 1, "total": 4 },
    "newTotals": null,
    "failing": 3,
    "pages": [
      {
        "url": "https://preview.example.com/",
        "httpStatus": 200,
        "issues": [
          {
            "ruleId": "image-alt",
            "title": "Images without alternative text",
            "impact": "critical",
            "wcag": ["1.1.1"],
            "helpUrl": "https://dequeuniversity.com/rules/axe/4.13/image-alt",
            "count": 1,
            "elements": [{ "target": ".hero > img", "html": "<img src=\"/hero.jpg\">" }]
          }
        ]
      }
    ]
  }
}

Hibák

A code mező állandó, a message embereknek szól (angolul).

HTTP	Kód	Jelentés
`400`	`INVALID_REQUEST`	A törzs vagy egy URL érvénytelen.
`401`	`UNAUTHORIZED`	Hiányzó, ismeretlen vagy visszavont kulcs.
`403`	`PLAN_REQUIRED`	A fiók csomagja nem tartalmaz API-hozzáférést.
`403`	`QUOTA_EXCEEDED`	Az ellenőrzés túllépné a havi oldalkeretet.
`404`	`NOT_FOUND / BASELINE_NOT_FOUND`	Nincs ilyen ellenőrzés vagy webhely a fiókjában.
`409`	`BUSY`	Már 2 ellenőrzés fut.
`429`	`RATE_LIMITED`	Túl sok kérés a kulccsal; lásd a Retry-After fejlécet.

Korlátok

Ellenőrzésenként 10 URL, fiókonként egyszerre 2 futó ellenőrzés
Kulcsonként percenként 120 kérés
Havi 500 ellenőrzött oldal a Growth, 2000 az Agency csomagban
Fiókonként legfeljebb 10 kulcs