Synthetische Shop-Prüfungen

Nutzen Sie synthetische Shop-Prüfungen, wenn Sie die echte Public Storefront, den Warenkorb, Checkout und das Payment-Handoff regelmäßig prüfen möchten, ohne Live-Analytics, Shop-Pulse oder kaufmännische KPIs zu verfälschen. Die Seite richtet sich an Entwickler, Betreiber und Integratoren, die automatisierte Prüfläufe gegen produktionsnahe öffentliche Hosts aufbauen.

Nach Abschluss läuft Ihr Prüflauf mit einem vertrauenswürdigen Ausführungskontext. Workspace speichert die entstehenden Warenkörbe, Bestellungen, Zahlungen, Seitenaufrufe und Attribution-Events getrennt von Live-Daten und meldet Storefront-Fehler über Public Storefront Telemetry.

Wann Sie diese Prüfung brauchen

commerce checkout smoke --dry-run bleibt bewusst nicht mutierend. Der Befehl erstellt keine Bestellung und keine Zahlung. Eine synthetische Shop-Prüfung läuft dagegen durch die echte Public Storefront und markiert die entstehenden Daten über den Ausführungskontext.

Voraussetzungen

• Die Public Storefront ist über den öffentlichen Host erreichbar.
• Der Warenkorb- und Checkout-Flow funktioniert für mindestens eine stabile Test-SKU, Menge, Lieferadresse und Zahlart.
• Ein Administrator hat einen geheimen Token-Wert erzeugt und nur dessen SHA-256-Hexwert in public.storefront.synthetic.execution.token_sha256 hinterlegt.
• Der Prüflauf kann HTTP-Header auf allen Storefront-Requests setzen. Für Browser-E2E-Tests eignet sich ein eigener Browser-Kontext mit globalen Extra- Headern.
• PayPal oder ein anderer Zahlungsanbieter läuft in einem Modus, der für regelmäßige technische Prüfläufe freigegeben ist. Prüfen Sie keine echten Kundenzahlungen ohne eigenen Prüfvertrag.

Ablauf

Senden Sie auf dem gesamten Prüflauf diese Header:

<Execution-Context-Header>: e2e_test
<Synthetic-Token-Header>: <geheimer-token-wert>

Für kürzere technische Smoke-Läufe können Sie statt e2e_test auch synthetic verwenden. Ohne gültigen Token lehnt Workspace mutierende Public- Commerce-Aufrufe mit synthetischem Kontext ab. Unmarkierte oder falsch markierte Requests zählen als live und dürfen deshalb nicht für regelmäßige Prüfbestellungen verwendet werden.

Der erste mutierende Schritt ist POST /api/v1/public/v1/cart. Workspace speichert den Ausführungskontext am Warenkorb. Bestellung, Payment- Transaktionen, Attribution und Engagement übernehmen diesen Kontext aus dem jeweiligen serverseitigen Vorgang.

Was getrennt wird

Public Storefront Telemetry

Das Standard-Storefront-Skript meldet diese Fehlerquellen an den öffentlichen Telemetry-Endpunkt:

POST /api/v1/public/v1/storefront/telemetry/report

Erlaubte Quellen sind:

• public.storefront.window.onerror
• public.storefront.unhandledrejection
• public.storefront.paypal.error
• public.storefront.checkout.request_failed

Der Endpunkt ist öffentlich, aber eng begrenzt. Er löst Tenant, Site und Sales Channel serverseitig aus dem Storefront-Scope auf, akzeptiert nur bekannte Quellen, speichert keine freien Admin-Payloads und nutzt Rate Limits. Verwenden Sie ihn nicht als allgemeine Logging-API.

Frontend-Script einbinden

Wenn Ihre Site den Default-Pagetype oder ein Pagetype mit main.mjs nutzt, ist Public Storefront Telemetry bereits eingebunden:

scripts:
  - main.mjs

main.mjs kommt aus den eingebetteten Default-Assets des Servers. Das Site-YAML verweist also nicht auf eine Datei im Site-Projekt, sondern auf einen Scriptnamen. Der Sitegenerator löst diesen Namen über den zusammengeführten Asset-Baum auf: zuerst Default-Assets, danach die Dateien des Site-Projekts. Wenn das Site-Projekt keine eigene scripts/main.mjs enthält, verwendet der Build das Default-Script und installiert Telemetry automatisch.

Wenn Sie scripts/main.mjs in der Site selbst anlegen, überschreiben Sie das Default-Script. Importieren und installieren Sie Telemetry dann selbst in Ihrem Entry-Script:

import { installPublicStorefrontTelemetry } from "./core/telemetry.mjs";

installPublicStorefrontTelemetry();

Für eigene Entry-Scripts gilt dieselbe Regel:

scripts:
  - shop.mjs

import { installPublicStorefrontTelemetry } from "./core/telemetry.mjs";

installPublicStorefrontTelemetry();
// eigener Shop-Code danach

core/telemetry.mjs ist ein Modul. Tragen Sie es nicht allein als YAML-Script ein, weil dadurch nur das Modul geladen wird. Die Installation passiert erst durch den Aufruf installPublicStorefrontTelemetry().

Beim Release-Build sammelt Workspace alle scripts:-Einträge aus Page- und Pagetype-YAML, baut sie mit esbuild und schreibt gehashte Asset-URLs in die HTML-Dateien. Importierte Module wie ./core/telemetry.mjs werden dabei in den Build einbezogen. Der Browser lädt deshalb im Release eine URL unter /assets/scripts/..., nicht zwingend /scripts/main.mjs.

Workspace komprimiert Release-Assets vor. Für JavaScript, CSS, HTML, JSON und weitere Textformate entstehen Brotli- und Gzip-Varianten, wenn sie kleiner als die Originaldatei sind. Der Browser ruft weiterhin die normale Asset-URL ab. Der Server liefert je nach Accept-Encoding bevorzugt Brotli und sonst Gzip.

Mit nucli prüfen

Lesen Sie vor automatisierten Storefront-Arbeiten den Agenten-Workflow:

nucli --tenant <tenant> skills show public-storefront

Prüfen Sie nicht mutierend, ob eine SKU grundsätzlich checkoutbereit ist:

nucli --tenant <tenant> commerce checkout smoke --site <site-id> --sku <sku> --quantity 1 --dry-run --json

Für einzelne Public-API-Aufrufe kann nucli api Header senden. Nutzen Sie das für technische Diagnose, nicht als Ersatz für einen echten Browser-E2E-Lauf:

printf '{}' | nucli --host https://shop.example.com api --anonymous \
  --input - \
  --summary \
  -H '<Execution-Context-Header>: e2e_test' \
  -H '<Synthetic-Token-Header>: <geheimer-token-wert>' \
  POST /api/v1/public/v1/cart

Erfolg erkennen

Eine synthetische Shop-Prüfung ist erfolgreich, wenn alle Punkte zutreffen:

• Storefront Context, Produktdetail, Pricing und Cart laden ohne öffentlichen Fehler.
• Add-to-Cart, Versand, Checkout Prepare, Zahlart und place-order laufen bis zum erwarteten Payment-Handoff.
• Die erzeugte Bestellung und ihre Payment-Transaktionen tragen execution_context=e2e_test oder execution_context=synthetic.
• Shop-Pulse, Site-Analytics und Kampagnen-Summaries ändern ihre Live-KPIs nicht durch den Prüflauf.
• Telemetry zeigt keine neuen Storefront-Fehler aus dem Prüflauf oder macht den Fehler mit Quelle, URL und sicherem Client-Kontext sichtbar.

Fehlerbilder

Geben Sie bei Eskalationen nur sichere Diagnosewerte weiter: Host, URL-Pfad, Zeitpunkt, Endpoint, HTTP-Status, allgemeiner Fehlercode, Site, Sales Channel, Locale, Test-SKU und Ausführungskontext. Geben Sie keine Cart Tokens, Zahlungs- Tokens, Kundendaten oder geheimen Synthetic Tokens weiter.