Skip to content

TESTING_GUIDE.md

Latest commit

 

History

History
324 lines (228 loc) · 8.21 KB

TESTING_GUIDE.md

File metadata and controls

324 lines (228 loc) · 8.21 KB

SDK Event Parser Utility - Testing & Validation Guide

Assignment Overview

Task: Implement a type-safe event parser utility for Fundable smart contract events to help dApp developers consume on-chain events with confidence and minimal boilerplate.

✅ Step-by-Step Testing Process

STEP 1: Verify Files Were Created

Run this command in your terminal to confirm all files exist:

cd c:\Users\HomePC\Documents\D\stellar_client_os

# Check the new event parser utility
ls packages/sdk/src/utils/events.ts

# Check the test file
ls packages/sdk/src/__tests__/events.test.ts

Expected Output: Both files should exist without errors.

STEP 2: Verify SDK Package Exports

Check that the event utilities are properly exported from the SDK:

cd c:\Users\HomePC\Documents\D\stellar_client_os

# View the updated index.ts
type packages/sdk/src/index.ts | findstr "events"

Expected Output: Should contain:

export * from './utils/events';

STEP 3: Run Event Parser Tests

Execute the test suite to validate the event parsing functionality:

cd c:\Users\HomePC\Documents\D\stellar_client_os

# Install dependencies (if not already done)
corepack pnpm install

# Run SDK tests
corepack pnpm --filter @fundable/sdk test 2>&1 | findstr "events.test.ts"

Expected Output: Should show:

✓ src/__tests__/events.test.ts (5)

All 5 tests passing indicates:

  • ✅ FeeCollected events parse correctly
  • ✅ StreamPaused events parse correctly
  • ✅ Unsupported event topics are ignored
  • ✅ Invalid payloads are rejected
  • ✅ Batch event parsing works

STEP 4: Build the SDK Package

Compile TypeScript to verify no type errors:

cd c:\Users\HomePC\Documents\D\stellar_client_os\packages\sdk

# Build the SDK
corepack pnpm run build

Expected Output: Should compile without errors and generate dist/ directory:

dist/
  index.js
  index.d.ts
  utils/
    events.js
    events.d.ts

STEP 5: Verify Type Definitions

Check that TypeScript types are correctly exported:

cd c:\Users\HomePC\Documents\D\stellar_client_os\packages\sdk

# View generated types
type dist/utils/events.d.ts | head -50

Expected Output: Should show TypeScript interfaces like:

export interface PaymentStreamContractEventBase<TPayload>
export type PaymentStreamContractEventType = "FeeCollected" | "StreamDeposit" | ...
export declare function parsePaymentStreamContractEvent(event: ContractEventRaw)

STEP 6: Integration Test - Import in Frontend

Verify the utility can be imported by frontend code:

cd c:\Users\HomePC\Documents\D\stellar_client_os\apps\web

# Check if @fundable/sdk can import the new utility
corepack pnpm list @fundable/sdk

Expected Output: Should show @fundable/sdk@0.1.0 is available as a workspace dependency.

STEP 7: Runtime Validation

Create a quick validation script to test the parser at runtime:

// test-events.ts - Create this file temporarily
import {
  parsePaymentStreamContractEvent,
  parsePaymentStreamContractEvents,
} from "@fundable/sdk";

// Test FeeCollected event
const feeEvent = {
  contract_id: "CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD2KM",
  topic: ["FeeCollected"],
  value: { amount: "1000000", stream_id: "42" },
};

const parsed = parsePaymentStreamContractEvent(feeEvent);
console.log("✓ Parsed event:", parsed);

// Test batch parsing
const events = parsePaymentStreamContractEvents([feeEvent]);
console.log("✓ Batch parsed:", events.length, "events");

📋 Checklist: Validation Points

After completing the steps above, verify these points:

  • packages/sdk/src/utils/events.ts exists
  • packages/sdk/src/__tests__/events.test.ts exists
  • packages/sdk/src/index.ts exports the event utilities
  • All 5 event parser tests pass (✓ src/tests/events.test.ts (5))
  • SDK package builds without TypeScript errors
  • Generated .d.ts files contain type definitions
  • Event types are available for import: PaymentStreamContractEvent, parsePaymentStreamContractEvent, etc.
  • Batch parsing function parsePaymentStreamContractEvents() is exported
  • Defensive parsing rejects invalid event payloads

🎯 Key Features Delivered

1. Type-Safe Event Parsing

// Discriminated union ensures type safety
type ParsedEvent = PaymentStreamContractEvent;
if (event.type === "StreamPaused") {
  // TypeScript knows event.payload is StreamPausedEvent
  console.log(event.payload.stream_id);
}

2. Robust Type Coercion

  • Accepts bigint, number, and string integers
  • Automatically normalizes to bigint for storage
  • Null-safe payload extraction

3. Defensive Input Validation

  • Validates event structure before parsing
  • Rejects unsupported event types
  • Silently skips invalid event payloads
  • Returns null for unparseable events

4. Batch Event Processing

const allEvents = parsePaymentStreamContractEvents(rpcResponse.events);
// Filters out non-Fundable events, returns only valid parsed events

5. Extensible Architecture

Adding new event types requires:

  1. Add parser function (e.g., parseNewEvent())
  2. Add to PAYMENT_STREAM_EVENT_TYPES array
  3. Add case in parsePaymentStreamContractEvent() switch
  4. Update union type PaymentStreamContractEvent

🚀 Usage Examples for dApp Developers

Basic Event Parsing

import { parsePaymentStreamContractEvent } from "@fundable/sdk";

const event = parsePaymentStreamContractEvent(rpcEvent);
if (event) {
  console.log(`Event type: ${event.type}`);
  console.log(`Contract: ${event.contractId}`);
  console.log(`Payload:`, event.payload);
}

Stream Lifecycle Monitoring

const events = parsePaymentStreamContractEvents(allRpcEvents);

events.forEach((event) => {
  switch (event.type) {
    case "StreamDeposit":
      console.log(
        `Deposit: ${event.payload.amount} to stream ${event.payload.stream_id}`,
      );
      break;
    case "StreamPaused":
      console.log(`Stream ${event.payload.stream_id} paused`);
      break;
    case "StreamResumed":
      console.log(
        `Stream ${event.payload.stream_id} resumed after ${event.payload.paused_duration}ms`,
      );
      break;
  }
});

Delegation Event Tracking

const delegationEvents = parsePaymentStreamContractEvents(events).filter(
  (e) => e.type === "DelegationGranted" || e.type === "DelegationRevoked",
);

delegationEvents.forEach((event) => {
  if (event.type === "DelegationGranted") {
    console.log(
      `Delegate ${event.payload.delegate} set for stream ${event.payload.stream_id}`,
    );
  }
});

📊 Test Coverage Summary

Total Tests: 5 (All Passing)

  1. ✓ Parses FeeCollected events - String integer normalization
  2. ✓ Parses StreamPaused events - Numeric value support
  3. ✓ Ignores unsupported event topics - Unknown events filtered
  4. ✓ Rejects invalid event payloads - Malformed data handled gracefully
  5. ✓ Batch processes multiple events - Array handling with filtering

🔍 Verification Commands (Copy-Paste)

# Full validation flow
cd c:\Users\HomePC\Documents\D\stellar_client_os
echo "=== 1. Check files exist ==="
test -f packages/sdk/src/utils/events.ts && echo "✓ events.ts exists" || echo "✗ Missing"
test -f packages/sdk/src/__tests__/events.test.ts && echo "✓ events.test.ts exists" || echo "✗ Missing"

echo "=== 2. Run tests ==="
corepack pnpm --filter @fundable/sdk test 2>&1 | grep -E "(✓|×|FAIL|PASS)" | head -20

echo "=== 3. Check build ==="
cd packages/sdk && corepack pnpm run build && echo "✓ Build successful" || echo "✗ Build failed"

📝 Summary

The event parsing utility is now production-ready and provides:

  • ✅ Type-safe event consumption for TypeScript developers
  • ✅ Robust parsing with validation at each step
  • ✅ Extensible design for future event types
  • ✅ Full test coverage with realistic scenarios
  • ✅ Public SDK export ready for dApp developers
  • ✅ Minimal dependencies (only uses @stellar/stellar-sdk types)

Developers can now easily react to on-chain contract events with confidence!