xc-mcp/dist/tools/simctl/push.d.ts

MCP server that wraps Xcode command-line tools for iOS/macOS development workflows

/**
 * Send simulated push notifications to an app on a simulator
 *
 * Examples:
 * - Simple alert: udid: "device-123", bundleId: "com.example.MyApp", payload: '{"aps":{"alert":"Test notification"}}'
 * - With badge: udid: "device-123", bundleId: "com.example.MyApp", payload: '{"aps":{"alert":"Test","badge":1}}'
 * - Complex payload: udid: "device-123", bundleId: "com.example.MyApp", payload: '{"aps":{"alert":{"title":"Title","body":"Body"},"sound":"default"},"custom":"data"}'
 * - With test context: udid: "device-123", bundleId: "com.example.MyApp", payload: '...', testName: "PushNotification_DeepLinkTest", expectedBehavior: "App navigates to ProductDetail view"
 *
 * Payload must be valid JSON with APS dictionary
 *
 * LLM Optimization:
 * Include testName and expectedBehavior for structured test tracking. Enables agents to verify
 * push delivery and validate app behavior against expectations.
 *
 * **Full documentation:** See simctl/push.md for detailed parameters and examples
 */
export declare function simctlPushTool(args: any): Promise<{
    content: {
        type: "text";
        text: string;
    }[];
    isError: boolean;
}>;
export declare const SIMCTL_PUSH_DOCS = "\n# simctl-push\n\nSend simulated push notifications to apps on simulators with test context tracking.\n\n## What it does\n\nSends push notifications with custom JSON payloads to apps, simulating remote notifications\nfrom APNS. Supports test tracking to verify push delivery and validate app behavior.\n\n## Parameters\n\n- **udid** (string, required): Simulator UDID (from simctl-list)\n- **bundleId** (string, required): App bundle ID (e.g., com.example.MyApp)\n- **payload** (string, required): JSON payload with APS dictionary\n- **testName** (string, optional): Test name for tracking\n- **expectedBehavior** (string, optional): Expected app behavior description\n\n## Payload Format\n\nMust be valid JSON with an \"aps\" dictionary:\n```json\n{\n  \"aps\": {\n    \"alert\": \"Notification text\",\n    \"badge\": 1,\n    \"sound\": \"default\"\n  },\n  \"custom\": \"Additional data\"\n}\n```\n\n## LLM Optimization\n\nThe **testName** and **expectedBehavior** parameters enable structured test tracking.\nThis allows AI agents to verify push notification delivery and validate that app behavior\nmatches expectations (e.g., navigation, UI updates, data refresh).\n\n## Returns\n\nJSON response with:\n- Push delivery status\n- Delivery information (sent timestamp)\n- Test context with expected vs actual behavior\n- Guidance for verifying notification handling\n\n## Examples\n\n### Simple alert notification\n```typescript\nawait simctlPushTool({\n  udid: 'device-123',\n  bundleId: 'com.example.MyApp',\n  payload: JSON.stringify({\n    aps: { alert: 'Test notification' }\n  })\n})\n```\n\n### Notification with badge and sound\n```typescript\nawait simctlPushTool({\n  udid: 'device-123',\n  bundleId: 'com.example.MyApp',\n  payload: JSON.stringify({\n    aps: {\n      alert: 'New message',\n      badge: 5,\n      sound: 'default'\n    }\n  })\n})\n```\n\n### Rich notification with custom data\n```typescript\nawait simctlPushTool({\n  udid: 'device-123',\n  bundleId: 'com.example.MyApp',\n  payload: JSON.stringify({\n    aps: {\n      alert: {\n        title: 'New Order',\n        body: 'Order #1234 has been placed'\n      },\n      badge: 1\n    },\n    orderId: '1234',\n    action: 'view_order'\n  })\n})\n```\n\n### Push with test context tracking\n```typescript\nawait simctlPushTool({\n  udid: 'device-123',\n  bundleId: 'com.example.MyApp',\n  payload: JSON.stringify({\n    aps: { alert: 'Product available' },\n    productId: '567'\n  }),\n  testName: 'PushNotification_DeepLinkTest',\n  expectedBehavior: 'App navigates to ProductDetail view for product 567'\n})\n```\n\n## Common Use Cases\n\n1. **Notification delivery testing**: Verify app receives and displays notifications\n2. **Deep link navigation**: Test notification taps navigate to correct screens\n3. **Badge updates**: Verify badge count is updated correctly\n4. **Custom data handling**: Test app processes custom payload data\n5. **Background behavior**: Test app behavior when notification arrives in background\n\n## Important Notes\n\n- **App must be running**: Launch app first or test background notification handling\n- **Payload validation**: JSON must be valid and include \"aps\" dictionary\n- **Immediate delivery**: Notification is delivered immediately (no delay)\n- **No user interaction**: Notification appears automatically without tapping\n- **Visual verification**: Use simctl-io screenshot to confirm notification display\n\n## Error Handling\n\n- **Invalid JSON**: Error if payload is not valid JSON\n- **App not running**: May fail if app is not running (test background handling)\n- **Simulator not booted**: Indicates simulator must be booted first\n- **Invalid bundle ID**: Validates bundle ID format (must contain '.')\n\n## Testing Workflow\n\n1. **Launch app**: `simctl-launch <udid> <bundleId>`\n2. **Send push**: `simctl-push <udid> <bundleId> <payload>`\n3. **Take screenshot**: `simctl-io <udid> screenshot` to verify delivery\n4. **Check navigation**: Verify app navigated to expected screen\n5. **Validate data**: Confirm app processed custom payload data\n\n## Test Context Tracking\n\nThe testContext in the response includes:\n- testName: Identifier for this push notification test\n- expectedBehavior: What should happen when notification is received\n- actualBehavior: What actually happened (delivery success/failure)\n- passed: Whether test passed\n\nThis enables agents to track push notification tests and verify expected behavior.\n\n## Advanced Testing\n\n- **Multiple notifications**: Send sequential pushes to test badge accumulation\n- **Different payload types**: Test alert, sound-only, silent notifications\n- **Content extensions**: Test notification service extensions with custom content\n- **Action buttons**: Test notification actions and user responses\n- **Notification grouping**: Test thread-id for notification grouping\n";
export declare const SIMCTL_PUSH_DOCS_MINI = "Send push notifications to simulator. Use rtfm({ toolName: \"simctl-push\" }) for docs.";
//# sourceMappingURL=push.d.ts.map