# Deeplink Test

> Test deep links and URL schemes in the iOS Simulator. Reads navigation/linking config, constructs test URLs, fires them via xcrun simctl, and verifies the resulting screen. Triggers on "test deep link", "test this URL scheme", "verify navigation to", "does deeplink work", "open URL in simulator", "test universal link".

- Skill: `ryanthedev/deeplink-test` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add ryanthedev/deeplink-test`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ryanthedev/deeplink-test/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ryanthedev (https://skillmd.com/u/ryanthedev)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ryanthedev/deeplink-test

---


# Skill: deeplink-test

**On load:** Read `../../.claude-plugin/plugin.json` from this skill's base directory. Display `deeplink-test v{version}` before proceeding.

Test deep links by reading the project's navigation config, constructing URLs, firing them into the iOS Simulator, and verifying the correct screen loads.

---

## Dependencies

| Skill / Resource | Why |
|------------------|-----|
| `ios-sim` | Step 5 — subagent uses `capture.sh view` (via `xcrun simctl screenshot` directly) to verify the screen after firing the deep link |
| `refs/react-native-docs` | Step 2 — docs search for deep linking patterns and universal link configuration |

---

## Scripts

- `${CLAUDE_SKILL_DIR}/scripts/openurl.sh <url>` — Validates and opens a URL in the booted simulator

## Workflow

### 1. Find the linking configuration

Search the user's project for navigation/linking config:

```
Glob: **/linking.{ts,js,tsx,jsx}
Glob: **/navigation/**/*.{ts,js,tsx,jsx}
Grep: "linking" or "prefixes" or "screens" in navigation files
```

Look for `linking` config objects containing `prefixes` and `screens` mapping.

### 2. Search docs for deep linking patterns

```
Grep the docs directory for deep linking reference:
  ${CLAUDE_SKILL_DIR}/../../refs/react-native-docs/
  Search terms: "deep link", "linking", "URL scheme", "universal link"
```

### 3. Construct the test URL

From the linking config, build a URL: `{prefix}{path}`.
If the user provided a specific URL, use it directly.
If testing a screen name, map it through the `screens` config to find the path.

### 4. Fire the URL into the simulator

```bash
${CLAUDE_SKILL_DIR}/scripts/openurl.sh "scheme://path/to/screen"
```

This wraps `xcrun simctl openurl booted` with validation.

### 5. Verify the screen loaded

Dispatch a subagent to capture and verify the simulator screen.

```
Dispatch Agent:
  subagent_type: general-purpose
  model: haiku
  description: "deeplink-test: verify deep link screen"
  prompt: |
    A deep link was just fired into the iOS Simulator.
    Expected destination: [EXPECTED_SCREEN]
    URL fired: [URL]

    1. Wait 2 seconds for navigation to settle, then run:
       xcrun simctl io booted screenshot /tmp/deeplink-verify.jpg
    2. Read /tmp/deeplink-verify.jpg to see the screen.
    3. Analyze and return:
       - Screen loaded: What screen/view is currently visible
       - Match: Does it match the expected destination? (PASS / FAIL)
       - Navigation state: Tab, stack depth, header title if visible
       - Errors: Any error messages, crash screens, or "not found" states
       - Details: Notable UI elements confirming the correct screen
    Return text only. Be concise.
```

### 6. Return results

Report to the user:
- **Result:** PASS or FAIL
- **URL fired:** The full URL tested
- **Screen loaded:** What the subagent observed
- **Navigation state:** Stack/tab context
- **Errors:** Any issues encountered

---

## Example Scenarios

| Scenario | URL | Expected |
|----------|-----|----------|
| Home screen | `myapp://home` | Home tab active |
| Product detail | `myapp://product/123` | Product screen with ID 123 |
| Nested settings | `myapp://settings/profile` | Profile under settings stack |
| Universal link | `https://myapp.com/share/abc` | Share screen with ID abc |
| Invalid path | `myapp://nonexistent` | Fallback or error screen |

## Tips

- Run `xcrun simctl list devices booted` to confirm a simulator is running before testing
- If the app isn't in the foreground, the deep link will cold-launch it — allow extra time
- Universal links require Associated Domains entitlement and an `apple-app-site-association` file
- Test both cold-start (app killed) and warm (app backgrounded) deep link scenarios
- For parameterized routes like `/product/:id`, test with real IDs from the app's data