Segment Event Testing Skill

The Problem

The recording gateway service and its companion microfrontend fire Segment analytics events at every stage of a document recording lifecycle — package creation, submission, confirmation, rejection. Testing those events meant manually crafting API requests through Swagger, acquiring and pasting auth tokens, filling out browser forms by hand, and cross-checking the Segment debugger. Each test run took 5–10 minutes, required reconstructing payloads from scratch every time, and left edge cases (rejection flows, multi-document packages, agent vs. human identity) largely untested because the overhead wasn’t worth it. With six distinct event types, multiple actor types, and client/server event parity to validate, the manual process was slow and fragile.

The Solution

I built a Claude Code skill invoked with a single slash command that accepts plain English and handles everything else. A tester can write “validate a deed package in Orange County” and get back a fired API call plus a formatted event verification report. “Run the full flow with 2 documents” executes validate → submit → notification in sequence. “Simulate a rejection for package TEST-123” fires the rejection path. “Test the MFE flow” launches a headless browser, fills the form, and captures client-side Segment payloads automatically. The skill checks whether dependent services are running before each test, acquires auth tokens on its own, constructs payloads with sensible defaults, and formats results in a consistent report. What previously took 5–10 minutes of error-prone setup now takes roughly 10 seconds and one sentence.

Outcome & Impact

Metric	Before	After
Time to test one flow	5–10 minutes	~10 seconds
Flows testable per session	2–3 before fatigue	Unlimited, including scheduled
Edge case coverage	Rarely tested manually	Trivially invocable
Client/server event parity	Never validated systematically	Built-in comparison mode

In active daily use for development testing, with planned team rollout once the underlying analytics code merges.

My Role & Contributions

Aspect	Detail
Role	Sole creator
Team size	Individual project
Timeline	1 day initial build, iterated after delivery
Scope	Skill design, intent vocabulary, API integration, Playwright browser testing, interactive mode
Key decisions	Natural language mapping strategy, default payload design, MFE auth bypass approach, identity resolution documentation

Technical Overview

The skill sits between a natural language interface and two separate test paths — a direct API path and a browser path — then unifies their output into a single event verification report.

┌──────────────────────────────────────────────────┐
│               /segment-test skill                │
│   (natural language → structured test calls)     │
├──────────────────────────────────────────────────┤
│                                                  │
│  Intent Parser                                   │
│    "validate a package in LA County"             │
│         ↓                                        │
│  Modifier Extraction                             │
│    jurisdiction, doc count, actor type           │
│         ↓                                        │
│  ┌───────────────┐    ┌──────────────────────┐   │
│  │  API Path     │    │  Browser Path        │   │
│  │               │    │                      │   │
│  │  curl → API   │    │  Playwright → MFE    │   │
│  │  gateway      │    │  Segment interceptor │   │
│  └───────┬───────┘    └──────────┬───────────┘   │
│          │                       │               │
│          ▼                       ▼               │
│  ┌────────────────────────────────────────────┐  │
│  │       Event Verification Report            │  │
│  │  ✓ Package Created — id, jurisdiction      │  │
│  │  ✓ Package Ready For Recording — mode      │  │
│  └────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────┘

Intent Parsing

A forgiving vocabulary layer maps multiple phrasings to the same underlying action — “validate,” “create,” and “start” all route to the validate endpoint. Modifiers like county name, document count, and actor type are extracted and used to construct the payload automatically, with defaults covering cases where details are omitted.

Environment Management

Before each test, the skill checks whether the gateway service and microfrontend are running. If either is down, it starts both in the background and polls until they’re healthy. This removes the most common source of friction in manual testing.

Token Management

Auth tokens are acquired via an OAuth2 client credentials grant. When credentials expire, the skill falls back gracefully to a user-provided token, avoiding silent failures mid-flow.

Dual-Path Event Testing

Server-side events are tested by firing curl requests at the API gateway and checking what arrives in Segment. Client-side events are tested by launching Playwright, injecting an unsigned token to bypass middleware auth checks (the microfrontend validates token expiry but not signature, making this a safe test-only exploit), and intercepting Segment payloads as the form is submitted. A comparison mode runs both paths side-by-side and diffs the event structures.

Challenges & Key Decisions

Designing a Forgiving Intent Vocabulary

A strict command syntax would have meant memorizing exact flags and parameter names — defeating the goal of reducing friction. I chose a loose natural language mapping where multiple phrasings collapse to the same action. This makes the skill usable without referencing documentation.

Documenting Non-Obvious Identity Behavior

During development I discovered that sending a specific actor-type header causes Segment events to drop the real user ID and substitute a generic system identifier. This was non-obvious and would have silently confused testers. Rather than noting it in a separate README, I embedded the explanation in the skill’s output at the moment it’s relevant — so the knowledge surfaces exactly when it matters.

MFE Auth Bypass Strategy

The microfrontend’s middleware checks token expiry but not signature, which made it possible for Playwright to inject unsigned tokens to bypass the auth layer during testing. I documented this as an intentional test-only approach rather than a vulnerability, since production validates signatures at the gateway level. Making the reasoning explicit prevents future contributors from “fixing” it and breaking the test path.

Scheduling Support for Timeliness Testing

Verifying that a notification callback fires events within SLA windows requires being present at the right moment — or being able to schedule a test to run later. I designed the flow abstraction to support deferred execution, enabling timeliness testing without manual coordination.

Tech Stack

Layer	Technologies
Skill Runtime	Claude Code
Server Testing	NestJS, Azure AD, Node.js
Browser Testing	Playwright, Next.js, Segment
Analytics	Segment
Auth	Azure AD, JWT

Lessons Learned

• Natural language beats rigid commands for developer tooling. The intent vocabulary approach means I never have to remember exact syntax. The cognitive overhead of “how do I invoke this” disappears, leaving only “what do I want to test.”
• Auto-starting dependencies removes the biggest source of friction. Half the pain of manual testing was uncertainty about whether services were running. Handling that silently in the skill made the remaining steps feel instant by comparison.
• Embed tribal knowledge in the tool, not a separate document. The non-obvious identity behavior would have caused repeated confusion. Surfacing the explanation at the moment of use — in the output itself — means the knowledge is impossible to miss.