stitch-sdk-bug-bash

Stitch SDK Bug Bash

This skill provides a framework and instructions for finding bugs in the Stitch SDK using a real API key. It guides you through exploring standard functional edge cases and tricky situations beyond the golden path.

The Mindset: Adversarial Exploration

When using this skill, do not just verify that the SDK works. Try to break it!

• Pass invalid or boundary parameters.
• Attempt operations on deleted or stale handles.
• Simulate unexpected API responses if possible or find edge cases where projection might fail.

Surface Areas to Cover

1. Root & Initialization (Stitch)

• Zero Config: Verify the singleton works without explicit config if STITCH_API_KEY is present.
• Invalid Config: Pass an empty API key or invalid base URL to StitchToolClient and verify that the first call fails with a clear authentication or connection error, not a generic noise error.

2. Project Lifecycle (Project)

• Handle Creation: Verify that stitch.project('invalid-id') does not throw (lazy instantiation) but the first call on it fails safely.
• Factory vs API: Verify that creating a project handle via the factory doesn't trigger API calls, but methods like project.listScreens() do.

3. Screen Lifecycle (Screen)

• The Handover: Verify that properties from Project.generate() are correctly populated on the returned Screen instances without a second fetch.
• Null Safety in Projections: Test tools or scenarios that return empty arrays or missing optional fields. Verify that the SDK handle handles them as undefined or empty arrays rather than crashing on null property access!

4. Design System (DesignSystem)

• Application: Create a design system, and apply it to a list of screens. Verify that if the list is empty or invalid, the SDK fails cleanly!
• Handles: Verify that project.designSystem('ds-id') correctly receives the projectId and injects it into calls like ds.apply(...).

Tricky Situations Matrix (Standard Functional Edges)

Diagnostic Hygiene

• Always wrap your test calls in try/catch.
• Log the error and inspect error.code or error.name to see if it's a StitchError or a generic raw error.
• If an execution throws a raw TypeError or "cannot read property of undefined", that is a HIGH PRIORITY BUG in the SDK's projection logic!

Test Template: The Full Workflow Bash

Use this template to run a quick end-to-end bash session.

import { stitch } from "@google/stitch-sdk";
 
async function bash() {