TL;DR
KI-Halluzinationen in 4 Schritten stoppen:
(1) Playwright installieren und Breakpoints konfigurieren (Desktop, Tablet, Mobil),
(2) Eine Screenshot-Testsuite erstellen, die die gesamte Seite, responsive Layouts und Interaktionen erfasst,
(3) ./qa-playwright-capture.sh ausführen, um Beweise zu sammeln,
(4) Den Reality Checker Agenten aktivieren, um Behauptungen mit Grep-Ergebnissen und Screenshots abzugleichen.
Agenten geben PASS oder ÜBERARBEITUNG NÖTIG mit spezifischen blockierenden Problemen aus – keine Fantasie-Genehmigungen mehr.
Einführung
Akzeptieren Sie nicht länger ein „sieht toll aus“ von KI-Agenten. Bauen Sie einen evidenzbasierten QA-Workflow mit Playwright-Screenshots auf, der visuellen Beweis vor jeder Genehmigung erfordert.
Probiere Apidog noch heute aus
Sie bitten einen KI-Agenten, Ihre Landingpage zu überprüfen. Er antwortet:
The design looks premium and polished. The glassmorphism effects are well-implemented. The page is fully responsive. Ready for production!
Sie öffnen die Seite. Der „Glassmorphismus“ ist ein einfarbiger grauer Hintergrund. Das „vollständig responsive“ Layout bricht auf Mobilgeräten. Nichts ist hochwertig oder ausgefeilt.
KI-Agenten halluzinieren. Sie sagen Ihnen, was Sie hören wollen. Sie vermeiden Konflikte. Sie genehmigen alles.
Der Reality Checker Agent aus der Agency-Sammlung verfolgt einen anderen Ansatz:
Status: NEEDS WORK
Evidence:
- grep for "glassmorphism" returned NO PREMIUM FEATURES FOUND
- responsive-mobile.png shows broken layout at 375px width
- test-results.json shows 3 console errors, 2.1s load time
Blocking issues: 4
Keine Gefühle. Keine Meinungen. Nur Beweise.
In diesem Tutorial erstellen Sie einen evidenzbasierten QA-Workflow, der Ihre API-Testpipeline ergänzt. Ob Sie Frontend-Layouts validieren oder API-Antworten in Apidog überprüfen, das Prinzip ist dasselbe: Fordern Sie Beweise vor der Genehmigung.
Sie werden Playwright für automatisierte Screenshot-Aufnahmen einrichten, obligatorische Realitätsprüfung-Befehle erstellen, Agenten-Behauptungen mit tatsächlichem Code abgleichen und eine PASS/FAIL-Zertifizierung vor der Auslieferung verlangen.
Warum Beweise wichtig sind
KI-Agenten sind Menschen-Pleaser. Sie wollen helfen. Sie wollen, dass Sie sie mögen. Also sagen sie, was gut klingt:
- „Der Code sieht solide aus!“ (nie getestet)
- „Die Performance sollte großartig sein!“ (nie gemessen)
- „Vollständig responsiv!“ (nie auf Mobilgeräten überprüft)
Evidenzbasierte QA ändert dies. Statt Meinungen erhalten Sie:
- Screenshots an Desktop-, Tablet-, Mobil-Breakpoints
- Performance-Metriken von tatsächlichen Seitenladezeiten
- Grep-Ergebnisse, die beweisen, dass Funktionen existieren (oder nicht)
- Konsolenfehleranzahlen aus Headless-Browser-Tests
Kein „vertrauen Sie mir“ mehr. Nur Beweis.
Schritt 1: Playwright einrichten
Playwright installieren:
npm install -D @playwright/test
npx playwright install chromium
qa-playwright.config.ts erstellen:
import { defineConfig } from '@playwright/test';
export default defineConfig({
testMatch: '**/qa-screenshots.spec.ts',
timeout: 30000,
use: {
baseURL: process.env.BASE_URL || 'http://localhost:8000',
screenshot: 'on',
trace: 'on-first-retry',
headless: true,
},
projects: [
{
name: 'desktop',
use: { viewport: { width: 1920, height: 1080 } },
},
{
name: 'tablet',
use: { viewport: { width: 768, height: 1024 } },
},
{
name: 'mobile',
use: { viewport: { width: 375, height: 667 } },
},
],
reporter: [['json', { outputFile: 'public/qa-screenshots/test-results.json' }]],
outputDir: 'public/qa-screenshots',
});
Schritt 2: Screenshot-Testsuite erstellen
qa-screenshots.spec.ts erstellen:
import { test, expect } from '@playwright/test';
import * as fs from 'fs';
import * as path from 'path';
// Ensure output directory exists
const outputDir = 'public/qa-screenshots';
if (!fs.existsSync(outputDir)) {
fs.mkdirSync(outputDir, { recursive: true });
}
test.describe('Reality Check Screenshots', () => {
test('capture full page at all breakpoints', async ({ page, browserName }) => {
const errors: string[] = [];
const consoleLogs: string[] = [];
// Capture console errors
page.on('console', msg => {
if (msg.type() === 'error') {
consoleLogs.push(`[ERROR] ${msg.text()}`);
}
});
// Capture network failures
page.on('requestfailed', request => {
errors.push(`[NETWORK] ${request.url()} failed`);
});
// Navigate to page
await page.goto('/');
await page.waitForLoadState('networkidle');
// Capture performance metrics
const metrics = await page.metrics();
const performance = {
jsHeapSize: metrics.JSHeapUsedSize,
loadTime: await page.evaluate(() => performance.timing.loadEventEnd - performance.timing.navigationStart),
domContentLoaded: await page.evaluate(() => performance.timing.domContentLoadedEventEnd - performance.timing.navigationStart),
};
// Save screenshot
const projectName = browserName || 'chromium';
await page.screenshot({
path: path.join(outputDir, `full-page-${projectName}.png`),
fullPage: true,
});
// Save metrics
fs.writeFileSync(
path.join(outputDir, 'performance-metrics.json'),
JSON.stringify({ performance, consoleErrors: consoleLogs, networkErrors: errors }, null, 2)
);
});
test('capture responsive layouts', async ({ page }) => {
const breakpoints = [
{ name: 'desktop', width: 1920, height: 1080 },
{ name: 'tablet', width: 768, height: 1024 },
{ name: 'mobile', width: 375, height: 667 },
];
for (const breakpoint of breakpoints) {
await page.setViewportSize({ width: breakpoint.width, height: breakpoint.height });
await page.goto('/');
await page.waitForLoadState('networkidle');
await page.screenshot({
path: path.join(outputDir, `responsive-${breakpoint.name}.png`),
fullPage: true,
});
}
});
test('capture navigation interactions', async ({ page }) => {
await page.goto('/');
// Find and click navigation items
const navItems = await page.$$('nav a, header a, .nav a');
for (let i = 0; i < Math.min(navItems.length, 5); i++) {
await page.screenshot({ path: path.join(outputDir, `nav-${i}-before.png`) });
await navItems[i].click();
await page.waitForLoadState('networkidle');
await page.screenshot({ path: path.join(outputDir, `nav-${i}-after.png`) });
await page.goBack();
await page.waitForLoadState('networkidle');
}
});
test('capture form interactions', async ({ page }) => {
await page.goto('/');
// Find forms
const forms = await page.$$('form');
for (let i = 0; i < forms.length; i++) {
const form = forms[i];
await form.screenshot({ path: path.join(outputDir, `form-${i}-initial.png`) });
// Fill inputs
const inputs = await form.$$('input[type="text"], input[type="email"], input[type="password"]');
for (const input of inputs) {
await input.fill('test@example.com');
}
await form.screenshot({ path: path.join(outputDir, `form-${i}-filled.png`) });
}
});
test('capture accordion/dropdown interactions', async ({ page }) => {
await page.goto('/');
// Find accordions
const accordions = await page.$$('[data-accordion], details, .accordion');
for (let i = 0; i < accordions.length; i++) {
await accordions[i].screenshot({ path: path.join(outputDir, `accordion-${i}-closed.png`) });
await accordions[i].click();
await page.waitForTimeout(300);
await accordions[i].screenshot({ path: path.join(outputDir, `accordion-${i}-open.png`) });
}
});
});
Schritt 3: Realitätsprüfungs-Skript erstellen
qa-playwright-capture.sh erstellen:
#!/usr/bin/env bash
#
# qa-playwright-capture.sh — Run Playwright screenshot captures for reality checking
#
# Usage: ./qa-playwright-capture.sh [BASE_URL] [OUTPUT_DIR]
#
set -euo pipefail
BASE_URL="${1:-http://localhost:8000}"
OUTPUT_DIR="${2:-public/qa-screenshots}"
echo "Starting Reality Check screenshot capture..."
echo " Base URL: $BASE_URL"
echo " Output: $OUTPUT_DIR"
# Ensure output directory exists
mkdir -p "$OUTPUT_DIR"
# Run Playwright tests
export BASE_URL
npx playwright test --config=qa-playwright.config.ts --grep "@screenshot"
# Generate summary
echo ""
echo "Generating summary..."
# Count screenshots
SCREENSHOT_COUNT=$(find "$OUTPUT_DIR" -name "*.png" | wc -l)
echo " Screenshots captured: $SCREENSHOT_COUNT"
# Check for console errors
if [ -f "$OUTPUT_DIR/performance-metrics.json" ]; then
ERROR_COUNT=$(cat "$OUTPUT_DIR/performance-metrics.json" | grep -c '"\[ERROR\]"' || echo "0")
echo " Console errors: $ERROR_COUNT"
fi
# Check load time
if [ -f "$OUTPUT_DIR/performance-metrics.json" ]; then
LOAD_TIME=$(cat "$OUTPUT_DIR/performance-metrics.json" | grep -o '"loadTime": [0-9.]*' | head -1 | awk '{print $2}')
echo " Load time: ${LOAD_TIME:-N/A}ms"
fi
echo ""
echo "Reality Check complete. Review screenshots in: $OUTPUT_DIR"
echo ""
echo "Next step: Run Reality Checker agent to validate evidence"
Ausführbar machen:
chmod +x qa-playwright-capture.sh
Schritt 4: Realitätsprüfungs-Befehle ausführen
Bevor ein KI-Agent die Arbeit genehmigen kann, führen Sie diese Befehle aus:
# 1. Verify what was actually built
ls -la resources/views/ || ls -la *.html
ls -la src/components/ || ls -la components/
# 2. Cross-check claimed features
grep -r "glassmorphism\|backdrop-filter\|blur" . --include="*.css" --include="*.html" || echo "NO GLASSMORPHISM FOUND"
grep -r "responsive\|media-query\|@media" . --include="*.css" || echo "NO RESPONSIVE CSS FOUND"
grep -r "jwt\|authentication\|auth" . --include="*.ts" --include="*.js" || echo "NO AUTH FOUND"
# 3. Run screenshot capture
./qa-playwright-capture.sh http://localhost:8000 public/qa-screenshots
# 4. Review evidence
ls -la public/qa-screenshots/
# Expected files:
# - responsive-desktop.png
# - responsive-tablet.png
# - responsive-mobile.png
# - nav-*-before.png, nav-*-after.png
# - form-*-initial.png, form-*-filled.png
# 5. Check metrics
cat public/qa-screenshots/test-results.json
cat public/qa-screenshots/performance-metrics.json
Schritt 5: Reality Checker Agent aktivieren
Eine Claude Code-Sitzung öffnen:
Activate Reality Checker mode.
Run your mandatory reality check process:
1. Verify files exist: ls -la src/components/
2. Cross-reference claimed features: grep for "premium", "glassmorphism"
3. Review screenshot evidence: public/qa-screenshots/
4. Check test-results.json for metrics
Project URL: http://localhost:8000
Output: PASS or NEEDS WORK with specific blocking issues.
Erwartete Ausgabe:
## Reality Check Results
### File Verification: PASS
- Component files present: 12 files found
- Expected structure matches
### Feature Verification: NEEDS WORK
- Claimed: "Premium glassmorphism design"
- grep result: NO GLASSMORPHISM FOUND
- Status: CLAIM NOT SUPPORTED
### Screenshot Evidence: NEEDS WORK
- Desktop (1920x1080): Layout correct
- Tablet (768x1024): Navigation overlap detected
- Mobile (375x667): Product grid broken (2 columns instead of 1)
### Performance Metrics: NEEDS WORK
- Load time: 2.3s (target: <1s)
- Console errors: 3 (target: 0)
- Network failures: 1 (target: 0)
## Final Status: NEEDS WORK
### Blocking Issues:
1. Glassmorphism claimed but not implemented
2. Mobile layout broken at 375px
3. Load time exceeds 1s target
4. 3 console errors to fix
### Non-Blocking:
- Tablet navigation overlap
- Add loading states
Do not approve until blocking issues are resolved.
Schritt 6: Behauptungen mit Beweisen abgleichen
Eine Behauptungs-Checkliste erstellen:
## Claims vs. Evidence Checklist
| Behauptung | Befehl für Beweise | Ergebnis |
|-------------------------|--------------------------|--------------------------------|
| "Premium Glassmorphismus" | grep "backdrop-filter" | NICHT GEFUNDEN |
| "Vollständig responsiv" | responsive-mobile.png | FEHLGESCHLAGEN (defektes Raster) |
| "Keine Konsolenfehler" | test-results.json | 3 Fehler gefunden |
| "Schnelle Ladezeit" | performance-metrics.json | 2.3s (Ziel: <1s) |
| "JWT-Authentifizierung" | grep "jsonwebtoken" | GEFUNDEN |
| "Ratenbegrenzung" | grep "rateLimit" | NICHT GEFUNDEN |
Aktualisieren Sie diese Checkliste für jedes Projekt. Fordern Sie für jede Behauptung Beweise an.
Vollständiger Realitätsprüfungs-Workflow
┌─────────────────────────────────────────────────────────────────┐
│ 1. Entwickler/KI schließt Arbeit ab │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ 2. Realitätsprüfungs-Befehle ausführen │
│ - ls zur Dateiüberprüfung │
│ - grep zur Funktionsüberprüfung │
│ - Playwright für Screenshots │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ 3. Reality Checker Agent aktivieren │
│ - Dateiüberprüfung überprüfen │
│ - Behauptungen abgleichen │
│ - Screenshots analysieren │
│ - Metriken überprüfen │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ 4. Ausgabe: BESTANDEN oder ÜBERARBEITUNG NÖTIG │
│ - BESTANDEN: Mit Zuversicht ausliefern │
│ - ÜBERARBEITUNG NÖTIG: Blockierende Probleme beheben, erneut ausführen│
└─────────────────────────────────────────────────────────────────┘
Integration in CI/CD
Realitätsprüfungen zu Ihrer CI-Pipeline hinzufügen:
# .github/workflows/qa-reality-check.yml
name: Reality Check
on: [pull_request]
jobs:
reality-check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Node
uses: actions/setup-node@v4
with:
node-version: '20'
- name: Install dependencies
run: npm ci
- name: Install Playwright
run: npx playwright install chromium
- name: Start server
run: npm start &
env:
PORT: 8000
- name: Wait for server
run: sleep 5
- name: Run reality check screenshots
run: ./qa-playwright-capture.sh http://localhost:8000 public/qa-screenshots
- name: Upload screenshots
uses: actions/upload-artifact@v4
if: always()
with:
name: reality-check-screenshots
path: public/qa-screenshots/
- name: Check for console errors
run: |
ERRORS=$(cat public/qa-screenshots/performance-metrics.json | grep -c '"\[ERROR\]"' || echo "0")
if [ "$ERRORS" -gt "0" ]; then
echo "Console errors found: $ERRORS"
exit 1
fi
- name: Check load time
run: |
LOAD_TIME=$(cat public/qa-screenshots/performance-metrics.json | grep -o '"loadTime": [0-9.]*' | head -1 | awk '{print $2}')
if (( $(echo "$LOAD_TIME > 1000" | bc -l) )); then
echo "Load time too slow: ${LOAD_TIME}ms (target: <1000ms)"
exit 1
fi
Was Sie erstellt haben
| Komponente | Zweck |
|---|---|
| Playwright-Konfiguration | Automatisierte Screenshot-Aufnahmen an 3 Breakpoints |
| Testsuite | Volle Seite, responsiv, Interaktionen |
| Realitätsprüfungs-Skript | Evidenzsammlung mit einem Befehl |
| Behauptungs-Checkliste | Abgleich von KI-Behauptungen mit Grep-Ergebnissen |
| CI/CD-Integration | Automatisierte Realitätsprüfungen bei PR |
Nächste Schritte
Workflow erweitern:
- Lighthouse-Integration für Performance-Scores hinzufügen
- Barrierefreiheits-Audits hinzufügen (axe-core)
- Visuelles Regressionstesting hinzufügen (Pixelvergleich)
Eine Behauptungsdatenbank aufbauen:
- Jede KI-Behauptung mit Evidenzstatus protokollieren
- Verfolgen, welche Agenten am häufigsten halluzinieren
- Genauigkeitsbewertungen im Laufe der Zeit erstellen
Mit Ihrem Team teilen:
- Den Realitätsprüfungs-Prozess dokumentieren
- Beweise vor jeder PR-Genehmigung anfordern
- „Zeig mir die Screenshots“ zu einer Team-Gewohnheit machen
Behebung häufiger Probleme
Playwright-Tests laufen ab:
- Timeout in der Konfiguration erhöhen:
timeout: 60000 - Überprüfen, ob der Server läuft:
curl http://localhost:8000 - Längere Wartezeit für Netzwerkleerlauf hinzufügen:
await page.waitForLoadState('networkidle', { timeout: 30000 }) - Im Headed-Modus zum Debuggen ausführen:
npx playwright test --headed
Screenshots werden nicht aufgenommen:
- Überprüfen, ob das Ausgabeverzeichnis existiert und beschreibbar ist:
mkdir -p public/qa-screenshots - Dateiberechtigungen überprüfen:
chmod 755 public/qa-screenshots - Sicherstellen, dass Chromium installiert ist:
npx playwright install chromium - Mit Debug-Ausgabe ausführen:
DEBUG=pw:api npx playwright test
Konsolenfehler werden nicht erfasst:
- Listener vor der Navigation hinzufügen:
page.on('console', ...)vorpage.goto() - Fehler-Typ-Filterung überprüfen:
msg.type() === 'error' - Alle Konsolenmeldungen zum Debuggen protokollieren:
page.on('console', msg => console.log(msg.text())) - Überprüfen, ob die Seite tatsächlich Inhalt lädt (keine leeren Screenshots)
Mobile Screenshots zeigen Desktop-Layout:
- Sicherstellen, dass der Viewport vor der Navigation eingestellt ist
- Mobilen User-Agent hinzufügen:
await page.setUserAgent('Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X)') - Geräteemulation verwenden:
use: { ...devices['iPhone 12'] } - Auf responsiven Meta-Tag in HTML prüfen:
<meta name="viewport" content="width=device-width">
CI/CD-Pipeline schlägt auf Ubuntu fehl:
- Systemabhängigkeiten installieren:
sudo apt-get install -y libnss3 libnspr4 libatk1.0-0 - Offizielles Playwright-Image verwenden:
mcr.microsoft.com/playwright:v1.40.0-jammy -
npx playwright install-depsvor der Installation der Browser ausführen -
--no-sandboxFlag für containerisierte Umgebungen hinzufügen
Erweiterte Realitätsprüfungs-Muster
Muster 1: Visuelles Regressionstesting
Screenshots mit Baselines vergleichen, um unbeabsichtigte Änderungen zu erkennen:
import { expect } from '@playwright/test';
test('visual regression check', async ({ page }) => {
await page.goto('/');
await expect(page).toHaveScreenshot('homepage-base.png', {
maxDiffPixels: 100, // Allow minor differences
fullPage: true,
});
});
Muster 2: Barrierefreiheits-Audit
axe-core für Barrierefreiheits-Beweise integrieren:
import AxeBuilder from '@axe-core/playwright';
test('accessibility audit', async ({ page }) => {
await page.goto('/');
const accessibilityScanResults = await new AxeBuilder({ page }).analyze();
// Save results
const fs = require('fs');
fs.writeFileSync(
'public/qa-screenshots/accessibility-results.json',
JSON.stringify(accessibilityScanResults, null, 2)
);
// Fail if critical violations
const criticalViolations = accessibilityScanResults.violations.filter(
v => v.impact === 'critical' || v.impact === 'serious'
);
expect(criticalViolations).toHaveLength(0);
});
Muster 3: Durchsetzung von Performance-Budgets
Builds fehlschlagen lassen, die Performance-Schwellenwerte überschreiten:
test('performance budget', async ({ page }) => {
await page.goto('/');
const metrics = await page.metrics();
const loadTime = await page.evaluate(() =>
performance.timing.loadEventEnd - performance.timing.navigationStart
);
// Budget thresholds
expect(loadTime).toBeLessThan(2000); // 2s max
expect(metrics.JSHeapUsedSize).toBeLessThan(5 * 1024 * 1024); // 5MB max
});
Ihre KI-Agenten können sich nicht länger mit „sieht toll aus“ durchmogeln.
Sie müssen ihre Arbeit mit Screenshots, Metriken und Grep-Ergebnissen beweisen.
Keine Halluzinationen mehr. Keine Fantasie-Genehmigungen mehr. Nur Beweise.
So sieht evidenzbasierte QA aus: Befehle ausführen, Screenshots überprüfen, Beweise anfordern.
Jetzt sind Sie dran: Fügen Sie Realitätsprüfungen zu Ihrem Workflow hinzu. Liefern Sie mit Zuversicht aus.
FAQ
Warum halluzinieren KI-Agenten bei der Code-Überprüfung?
KI-Agenten sind darauf trainiert, hilfreich und gefällig zu sein. Sie antworten mit dem, was gut klingt, anstatt mit dem, was verifiziert ist. Ohne Beweisanforderungen sagen sie „sieht toll aus“, um Konflikte zu vermeiden.
Wie richte ich Playwright für Screenshot-Tests ein?
Installieren Sie mit npm install -D @playwright/test, führen Sie npx playwright install chromium aus, erstellen Sie eine Konfigurationsdatei mit Viewport-Breakpoints und schreiben Sie Testsuites, die Screenshots an jedem Breakpoint aufnehmen.
Welche Realitätsprüfungs-Befehle sollte ich vor der Genehmigung ausführen?
Führen Sie ls aus, um die Existenz von Dateien zu überprüfen, grep, um zu verifizieren, dass behauptete Funktionen im Code existieren, Playwright-Tests für Screenshots und überprüfen Sie test-results.json auf Konsolenfehler und Performance-Metriken.
Was ist der Reality Checker Agent?
Reality Checker ist ein spezialisierter KI-Agent von The Agency, der Arbeiten anhand von Beweisen validiert. Er führt Verifizierungsbefehle aus, überprüft Screenshots, gleicht Behauptungen ab und gibt BESTANDEN oder ÜBERARBEITUNG NÖTIG mit spezifischen blockierenden Problemen aus.
Wie integriere ich Realitätsprüfungen in CI/CD?
Fügen Sie einen GitHub Actions Workflow hinzu, der Playwright installiert, Ihren Server startet, Screenshot-Aufnahmen ausführt, Artefakte hochlädt und den Build fehlschlagen lässt, wenn Konsolenfehler 0 überschreiten oder die Ladezeit Ihren Schwellenwert überschreitet.
Was, wenn Screenshots Probleme zeigen, aber der Agent sagt BESTANDEN?
Der Agent ist falsch konfiguriert. Der Reality Checker muss Beweise überprüfen, bevor er den Status ausgibt. Trainieren Sie ihn neu, um Folgendes zu verlangen: (1) Grep-Ergebnisse, die Funktionen belegen, (2) Screenshot-Überprüfung, (3) Metriken innerhalb der Schwellenwerte.
Wie bringe ich mein Team dazu, evidenzbasierte QA einzuführen?
Dokumentieren Sie den Realitätsprüfungs-Prozess, fügen Sie CI/CD-Gates hinzu, die das Bestehen von Tests erfordern, machen Sie die Screenshot-Überprüfung für die PR-Genehmigung obligatorisch und verfolgen Sie, welche Agenten die genauesten Bewertungen liefern.
Top comments (0)