ngDRR E2E Tester

End-to-end tesztelő keretrendszer az ngDRR mikroszerviz-ökoszisztémához. YAML-alapú deklaratív tesztfolyamatok futtatása webes felületen keresztül, valós idejű SSE visszajelzéssel.

Tartalom

• Áttekintés
• Architektúra
• Funkciók
• Telepítés és fejlesztés
• Konfiguráció
• Tesztfolyamatok írása
• Lépéstípusok
• API végpontok
• Éles telepítés (Docker)
• Mappastruktúra

---

Áttekintés

Az E2E Tester egy önálló webalkalmazás, amely az ngDRR rendszer összes rétegét képes tesztelni:

• REST API végpontok (HTTP kérések + JSON Path assertiók)
• EPP protokoll (XML over TCP socket, XPath assertiók)
• Böngésző műveletek (Playwright távoli WebSocket-en keresztül)
• E-mail ellenőrzés (MailDev integráció)
• Adatbázis assertiók (PostgreSQL docker exec vagy közvetlen TCP)
• Bruno CLI kollekciók futtatása

A tesztfolyamatok YAML fájlokban vannak definiálva, 3 szintű hierarchiával: Flow → Sub-flow → Test Case → Steps.

Architektúra

┌─────────────────────┐     SSE / REST      ┌──────────────────┐
│   Next.js 16 (web)  │◄──────────────────►│   Go Backend     │
│   shadcn/ui v4      │     port 3011       │   port 8380      │
│   Tailwind CSS v4   │                     │                  │
└─────────────────────┘                     │  ┌────────────┐  │
                                            │  │ Engine     │  │──► ngDRR API (HTTP)
                                            │  │ Scheduler  │  │──► PostgreSQL (docker exec / TCP)
                                            │  │ SSE Hub    │  │──► EPP Server (TCP socket)
                                            │  │ SQLite DB  │  │──► MailDev (HTTP API)
                                            │  └────────────┘  │──► Playwright (WebSocket)
                                            └──────────────────┘──► Bruno CLI (subprocess)
                                                     │
                                                     ▼
                                              data/e2e-tester.db

Komponens	Technológia
Backend	Go 1.25+, net/http stdlib router
Frontend	Next.js 16 (App Router), React 19, shadcn/ui v4 (Base UI), Tailwind CSS v4
Adatbázis	SQLite (ncruces/go-sqlite3, CGo-free, Wasm-alapú)
Valós idő	Egyedi SSE hub (channel-alapú, külső függőség nélkül)
Böngésző	Playwright Node.js subprocess, távoli WebSocket
Ütemezés	robfig/cron/v3 (cron kifejezés), Mattermost webhook értesítés

Funkciók

• Deklaratív YAML tesztfolyamatok — változó-interpoláció Go template szintaxissal
• 7 lépéstípus — HTTP, EPP, Browser, Mail, DB, Context, Bruno
• 3 szintű hierarchia — Flow → Sub-flow → Test Case
• Valós idejű végrehajtás — SSE stream lépésenkénti státuszfrissítéssel
• Assertion rendszer — status_code, json_path, xpath, mail_subject, mail_body, row_count, stb.
• Változókezelés — 3 scope (env, vars, global), lépések közötti adatátadás
• Megerősítési stratégiák — db_bypass, auto_confirm, manual_pause
• Ütemezett futtatások — cron-alapú, tag/flow szűrés, Mattermost értesítések
• SigNoz integráció — szerviz logok lekérdezése futtatáshoz kötve
• Bruno CLI runner — meglévő Bruno kollekciók futtatása a keretrendszerből
• Screenshot-ok — böngésző lépéseknél automatikus képernyőkép mentés
• Konfiguráció UI — környezetek, integrációk kezelése a webes felületen
• Retention — automatikus régi futtatások és screenshot-ok törlése

Telepítés és fejlesztés

Előfeltételek

• Go 1.25+
• Node.js 24+ és npm
• Task (taskfile.dev) — build és fejlesztői parancsok
• Docker — PostgreSQL, MailDev, Playwright browser server
• Futó ngDRR környezet (API, PostgreSQL, EPP szerver)

Gyors indítás

# 1. Projekt klónozás
git clone <repo-url> && cd ngdrr-e2e-tester

# 2. Inicializálás (.env fájl + bin/ mappa létrehozása)
task init

# 3. Frontend függőségek
cd web && npm install && cd ..

# 4. (Opcionális) Playwright böngészők telepítése
task pw:setup

# 5. (Opcionális) Bruno CLI telepítése
task bruno:install

# 6. Fejlesztői szerver indítása (backend + frontend)
task dev:all

A backend a http://127.0.0.1:8380, a frontend a http://127.0.0.1:3011 címen lesz elérhető.

Elérhető Task parancsok

Parancs	Leírás
task init	Projekt inicializálás (.env + bin/)
task build	Go bináris fordítása → bin/e2e-tester
task dev	Backend indítása (Bruno install + Go run)
task dev:all	Backend + frontend együtt
task test	Go tesztek futtatása (race detector)
task fmt	Go kód formázás (gofmt + gofumpt + goimports)
task vet	Statikus analízis (go vet + staticcheck)
task web:dev	Next.js dev szerver
task web:build	Next.js production build
task db:reset	SQLite adatbázis törlése
task pw:setup	Playwright + Chromium telepítése
task bruno:install	Bruno CLI telepítése

Konfiguráció

config.yaml

A fő konfigurációs fájl a projekt gyökerében. Környezetenként külön szekció definiálható:

retention:
  max_runs: 50                    # Megőrzött futtatások száma
  cleanup_screenshots: true       # Régi screenshot-ok törlése

environments:
  - id: localhost
    name: Localhost
    base_url: http://localhost:80           # ngDRR API base URL
    webapp_url: http://localhost:3000       # ngDRR webapp URL
    mail_catcher_url: http://localhost:18025/email  # MailDev API
    credentials:
      email: admin@example.com
      password: secret
    database:
      host: localhost
      port: 5432
      user: user_db_admin
      db_name: ngdrr
      ssl_mode: disable
      container: ngdrr-postgres             # Docker container neve (db_mode: docker)
    db_mode: docker                         # "docker" = docker exec, "network" = TCP
    browser_concurrency: 5                  # Max párhuzamos böngésző művelet
    webapp_session_cookie: ngdrr-session    # Cookie neve a webapp-ban
    webapp_session_expiry_key: session-key
    epp:
      host: "127.0.0.1"
      port: 4701
      client_id: "baca6b64b09fa9be"
      password: "12345678"
      ident_line: "PROXY TCP4 ..."
    is_default: true

bruno:
  collection_path: /path/to/Bruno/Collections/ngDRR

integrations:
  signoz:
    endpoint: http://localhost:8080         # SigNoz API URL
    api_key: ""
  webhook:
    url: http://host.docker.internal:4040/mattermost  # Mattermost webhook

Környezeti változók

A következő környezeti változók felülírják a config.yaml megfelelő értékeit (üres config érték esetén):

Változó	Alapértelmezett	Leírás
API_PORT	8380	Go backend HTTP port
WEB_PORT	3011 (dev) / 3000 (prod)	Next.js frontend port
NEXT_PUBLIC_API_PORT	—	Frontend SSE közvetlen csatlakozás portja (Next.js proxy pufferel)
PLAYWRIGHT_WS_ENDPOINT	—	Távoli Playwright böngésző WebSocket URL (ws://host:3400/ws)
BROWSER_PORT	3400	Browser server container port
SIGNOZ_WEB_ENDPOINT	—	SigNoz API URL (fallback)
SIGNOZ_KEY	—	SigNoz API kulcs (fallback)
WEBHOOK_URL	—	Mattermost webhook URL (fallback)
E2E_BASE_URL	—	E2E Tester publikus URL (értesítésekben használt linkekhez)

Tesztfolyamatok írása

A tesztfolyamatok a flows/ mappában találhatók. Minden flow egy külön almappában van saját flow.yaml fájllal.

Könyvtárstruktúra

flows/
├── authentication/
│   ├── flow.yaml           # Flow definíció
│   └── login.yaml          # Sub-flow: bejelentkezés
├── contacts/
│   ├── flow.yaml
│   ├── creation.yaml       # Sub-flow: contact létrehozás
│   ├── queries.yaml        # Sub-flow: contact lekérdezések
│   └── email-notifications.yaml
├── epp-contacts/
│   ├── flow.yaml
│   └── create-contact.yaml
└── bruno-contact/
    └── flow.yaml

Flow definíció (flow.yaml)

flow:
  id: contacts                    # Egyedi azonosító (mappa nevével egyezzen)
  name: Contact végpontok         # Megjelenítendő név
  tags: [regression]              # Szűréshez használt címkék
  type_tags: [API, Browser, Mail] # Lépéstípus címkék (UI-ban megjelenik)
  order: 3                        # Rendezési sorrend a dashboardon

sub_flows:
  - id: creation
    file: creation.yaml           # Sub-flow YAML fájl
    order: 2
    depends_on: [login]           # Más sub-flow-któl való függőség

Sub-flow és test case definíció

sub_flow:
  id: creation
  name: Contact létrehozás
  confirmation_strategy: none     # none | db_bypass | auto_confirm | manual_pause
  estimated_duration: 30s
  depends_on_global: [session_token]  # Globális változó függőség

test_cases:
  - id: create-zero-factor-contact
    name: 0 faktoros contact létrehozás
    tags: [contact, create]
    type_tags: [API]
    order: 1
    allowed_to_fail: true         # Ismert hibás teszt (nem okoz flow-szintű hibát)
    steps:
      - id: step1
        type: http
        # ... lépés definíció

Visszafelé kompatibilitás: Ha a YAML-ben közvetlenül steps: van test_cases: helyett, az automatikusan egyetlen implicit test case-ként kerül feldolgozásra.

Változó-interpoláció

A YAML értékekben Go template szintaxis használható:

Kifejezés	Leírás
{{ .vars.contact_id }}	Lokális változó (test case scope)
{{ .global.session_token }}	Globális változó (flow scope, lépések közötti)
{{ .env.base_url }}	Környezeti érték a config.yaml-ból
{{ uuid }}	Új UUID generálás
{{ date_prefix }}	Dátum prefix (YYYYMMDD formátum)
{{ random_slug }}	Véletlen 6 karakteres slug
{{ random_digits 8 }}	N darab véletlen számjegy
{{ random_ip }}	Véletlen IP cím
{{ recent_rfc3339 }}	Közelmúltbeli RFC3339 időbélyeg

Változó kinyerés (extract)

Lépés válaszából változóba mentés:

extract:
  contact_id: "data.contactId"              # JSON path → vars scope
  session_token:
    json_path: "data.sessionToken"
    scope: global                            # Globális scope-ba mentés

Lépéstípusok

http — REST API hívás

- id: create_contact
  type: http
  request:
    method: POST
    path: /v1/contacts
    headers:
      x-ngdrr-session-token: "{{ .global.session_token }}"
    body:
      name: "{{ .vars.contact_name }}"
      email: "test@example.com"
  assertions:
    - status_code: 200
    - json_path: "data.contactId"
      is_not_empty: true
    - json_path: "meta.code"
      equals: "http.ok"
  extract:
    contact_id: "data.contactId"

epp_connect / epp — EPP protokoll

# Kapcsolat felépítése
- id: connect
  type: epp_connect

# EPP parancs küldése
- id: create_contact
  type: epp
  epp:
    command: |
      <?xml version="1.0" encoding="UTF-8"?>
      <epp xmlns="urn:ietf:params:xml:ns:epp-1.0">
        <command>
          <create>
            <contact:create xmlns:contact="urn:ietf:params:xml:ns:contact-1.0">
              <contact:id>{{ .vars.contact_handle }}</contact:id>
              ...
            </contact:create>
          </create>
        </command>
      </epp>
  assertions:
    - xpath: "//epp:result/@code"
      equals: "1000"
  extract:
    contact_id: "xpath://epp:creData/contact:id"

browser — Playwright böngésző

- id: login_webapp
  type: browser
  browser:
    steps:
      - action: navigate
        url: "{{ .env.webapp_url }}/login"
      - action: fill
        selector: "input[name='email']"
        value: "{{ .env.credentials.email }}"
      - action: click
        selector: "button[type='submit']"
      - action: screenshot
        name: "after-login"
      - action: wait_for_selector
        selector: "[data-testid='dashboard']"
        timeout: 10000

A browser szerver külön Docker containerben fut (Dockerfile.browser, port 3400).

mail — MailDev e-mail ellenőrzés

- id: check_email
  type: mail
  mail:
    action: fetch              # fetch | count | delete_all
    timeout: "5s"              # Várakozás az e-mail megérkezésére (retry 500ms után)
    filter:
      to: "test@example.com"  # Címzett szűrő (exact match)
      subject_contains: "megerősítés"
  assertions:
    - mail_subject: "megerősítő kód"
    - mail_body: "{{ .vars.contact_name }}"
    - mail_header: "x-ngdrr-notification-id"
      is_not_empty: true
  extract:
    confirm_code: "regex:kód:\\s+([A-Z0-9-]+)"
    notification_id: "header:x-ngdrr-notification-id"

db — PostgreSQL assertiók

- id: check_contact_in_db
  type: db
  db:
    query: "SELECT status FROM contact.contacts WHERE id = '{{ .vars.contact_id }}'"
  assertions:
    - row_count: 1
    - column: "status"
      row: 0
      equals: "active"

A lekérdezés docker exec (db_mode: docker) vagy közvetlen TCP (db_mode: network) módban fut.

context — Tesztadat generálás

- id: gen_name
  type: context
  action: generate
  template: "E2E {{ date_prefix }} {{ random_slug }}"
  store_as: contact_name        # → vars.contact_name

bruno — Bruno CLI kollekció futtatás

flow:
  id: bruno-contact-tests
  type: bruno                   # A teljes flow Bruno típusú
  tags: ["contact", "api"]
bruno:
  target: "Contact"             # Mappa vagy .bru fájl (opcionális, üres = teljes kollekció)
  environment: "local"          # Bruno environment neve
  auto_login: true              # Automatikus auth token beszerzés

A Bruno kollekció elérési útját a config.yaml bruno.collection_path határozza meg.

Assertiók összefoglaló

Típus	Leírás	Használható
status_code	HTTP státuszkód egyezés	HTTP
json_path + equals	JSON path érték egyezés	HTTP
json_path + is_not_empty	JSON path létezik és nem üres	HTTP
xpath + equals	XPath érték egyezés	EPP
xpath + is_not_empty	XPath létezik és nem üres	EPP
row_count	SQL eredmény sorok száma	DB
column + equals	SQL oszlop értéke adott sorban	DB
mail_subject	E-mail tárgy tartalmazza	Mail
mail_body	E-mail törzs tartalmazza	Mail
mail_header + equals	E-mail fejléc értéke	Mail
mail_header + is_not_empty	E-mail fejléc létezik	Mail
mail_count	E-mailek száma (count action)	Mail

API végpontok

Futtatások

Módszer	Útvonal	Leírás
GET	/api/flows	Összes flow listázása
GET	/api/flows/{id}	Egy flow részletei
POST	/api/runs	Új futtatás indítása
GET	/api/runs	Futtatások listázása (szűrők: flow_id, status, scheduled, limit, offset)
GET	/api/runs/{id}	Futtatás részletei
GET	/api/runs/{id}/steps	Lépéseredmények
GET	/api/runs/{id}/stream	SSE stream (valós idejű események)
POST	/api/runs/{id}/confirm	Manuális megerősítés (manual_pause)
POST	/api/runs/{id}/cancel	Futtatás megszakítása

Konfiguráció

Módszer	Útvonal	Leírás
GET	/api/environments	Környezetek listázása
POST	/api/environments	Új környezet létrehozása
PUT	/api/environments/{id}	Környezet módosítása
DELETE	/api/environments/{id}	Környezet törlése
GET	/api/integrations	Integrációs beállítások lekérdezése
PUT	/api/integrations	Integrációs beállítások mentése

Ütemezés

Módszer	Útvonal	Leírás
GET	/api/schedule	Ütemezés konfigurációja
PUT	/api/schedule	Ütemezés mentése
POST	/api/schedule/trigger	Azonnali ütemezett futtatás indítása
GET	/api/schedule/status	Ütemező állapota

Egyéb

Módszer	Útvonal	Leírás
GET	/api/health	Health check
GET	/api/version	Verzió és build info
GET	/api/signoz/services	SigNoz szerviz lista
GET	/api/runs/{id}/logs	SigNoz logok egy futtatáshoz
GET	/api/runs/{id}/logs/link	"Megnyitás SigNoz-ban" deep link
GET	/api/screenshots/{runId}/{stepId}/{filename}	Screenshot fájl
GET	/api/bruno/collection	Bruno kollekció struktúra
POST	/api/bruno/collection/refresh	Bruno index újraépítése

Éles telepítés (Docker)

Image-ek

Két Docker image szükséges:

1. e2e-tester — Multi-stage build (Go bináris + Next.js standalone)

   • Portok: 3000 (frontend), 8380 (backend API)
   • Volume: /app/data (SQLite DB + screenshot-ok)
   • Config: /app/config.yaml és /app/flows/

2. e2e-tester-browser — Playwright browser szerver

   • Port: 3400 (WebSocket endpoint)
   • Base image: mcr.microsoft.com/playwright:v1.50.0-noble

Docker Swarm deploy

A deploy/services.yaml tartalmazza a teljes stack definíciót:

docker stack deploy -c deploy/services.yaml e2e-tester

Szervizek:

• e2e-tester — fő alkalmazás (port 3110 → 3000)
• e2e-tester-browser — Playwright szerver (port 3400)
• maildev — MailDev levelezőszerver (port 18025 web, 1025 SMTP)

Új környezet beállítása

1. config.yaml testreszabása — új environment hozzáadása az environments listához:

   • base_url: az ngDRR API elérhetősége
   • webapp_url: a webapp URL-je
   • credentials: bejelentkezési adatok
   • database: PostgreSQL elérhetőség (host, port, user, db_name)
   • db_mode: docker (ha Docker container-en belül futtatjuk) vagy network (közvetlen TCP)
   • epp: EPP szerver elérhetősége

2. Környezeti változók beállítása:

   • PLAYWRIGHT_WS_ENDPOINT=ws://<browser-host>:3400/ws
   • SIGNOZ_WEB_ENDPOINT és SIGNOZ_KEY (ha SigNoz elérhető)
   • WEBHOOK_URL (ha Mattermost értesítés kell)
   • E2E_BASE_URL (publikus URL az értesítésekben)

3. Hálózat: az E2E Tester-nek el kell érnie:

   • ngDRR API-t (base_url)
   • PostgreSQL-t (docker socket vagy TCP)
   • EPP szervert (TCP)
   • MailDev-et (HTTP API)
   • SigNoz-ot (HTTP API, opcionális)
   • Playwright browser szervert (WebSocket)

4. Volume: a /app/data könyvtár persistens legyen (SQLite DB + screenshot-ok).

Mappastruktúra

ngdrr-e2e-tester/
├── cmd/server/
│   └── main.go                 # Belépési pont
├── internal/
│   ├── api/                    # HTTP handler-ek
│   ├── server/                 # HTTP szerver, routing, middleware
│   ├── engine/                 # Tesztfuttató motor (minden lépéstípus)
│   ├── flow/                   # YAML flow regisztráció és modellek
│   ├── store/                  # SQLite perzisztencia + migrációk
│   ├── environment/            # Konfiguráció kezelés (config.yaml)
│   ├── scheduler/              # Cron ütemező + webhook értesítő
│   ├── signoz/                 # SigNoz API kliens
│   ├── sse/                    # SSE pub/sub hub
│   ├── bruno/                  # Bruno CLI futtatás és indexelés
│   ├── playwright/             # Playwright böngésző lépések
│   ├── auth/                   # ngDRR session kezelés
│   └── bootstrap/              # Verzió konstansok (build-time)
├── flows/                      # YAML tesztfolyamatok
│   ├── authentication/
│   ├── contacts/
│   ├── domains/
│   ├── users/
│   ├── notifications/
│   ├── epp-contacts/
│   └── bruno-contact/
├── web/                        # Next.js 16 frontend
│   ├── src/app/                # App Router oldalak
│   ├── src/components/         # shadcn/ui + egyedi komponensek
│   ├── src/hooks/              # React hookok (SSE, store)
│   └── src/lib/                # Utility-k, API kliens
├── tools/
│   ├── playwright/             # Playwright Node.js runner
│   └── bruno/                  # Bruno CLI (bun)
├── deploy/
│   ├── config.yaml             # Éles konfiguráció sablon
│   ├── services.yaml           # Docker Swarm stack
│   ├── environment.yaml        # Swarm constraint-ek
│   └── entrypoint.sh           # Container indító script
├── design/                     # UI mockupok (.pen fájlok)
├── data/                       # Futásidejű adatok (gitignored)
├── config.yaml                 # Lokális fejlesztői konfiguráció
├── Dockerfile                  # Fő alkalmazás (Go + Next.js)
├── Dockerfile.browser          # Playwright browser szerver
├── Taskfile.yml                # Task parancsok
├── go.mod / go.sum
└── README.md

Meglévő tesztfolyamatok

Flow ID	Név	Típus	Leírás
authentication	Hitelesítés	API	Bejelentkezés, session kezelés
users	Felhasználói végpontok	API	User CRUD műveletek
contacts	Contact végpontok	API, Browser, Mail	Contact létrehozás, módosítás, e-mail ellenőrzés
domains	Domain végpontok	API	Domain regisztráció és kezelés
notifications	Notification végpontok	API	Értesítések tesztelése
epp-contacts	EPP Kontakt kezelés	EPP	EPP protokollon keresztüli kontakt műveletek
bruno-contact-tests	Contact API tesztek (Bruno)	Bruno	Bruno kollekció alapú API tesztek

Licenc

Belső projekt — nem publikus.