@danecodes/roku-deeplink

Deep link test runner and validator for Roku channels. Define test cases, run them against a device, and get a pass/fail report — one command to validate all your deep links before submitting for Roku certification.

Built on @danecodes/roku-ecp.

Install

npm install @danecodes/roku-deeplink

Quick start

Generate a template config:

roku-deeplink init

Edit deeplinks.json with your content IDs, then run:

roku-deeplink run deeplinks.json --device 192.168.0.30

Deep Link Test Results
═══════════════════════
✓ Movie playback           (3.2s)
✓ Series details page      (2.1s)
✗ Episode direct play      (15.0s) — playback did not start within 15000ms
✓ Short form content       (1.8s)
✓ Invalid content ID       (2.5s)
✓ Home screen              (1.2s)

5/6 passed (25.8s total)

Config file

{
  "channelId": "dev",
  "tests": [
    {
      "name": "Movie playback",
      "contentId": "MOVIE_001",
      "mediaType": "movie",
      "expect": {
        "playback": true,
        "playbackTimeout": 15000,
        "noErrors": true
      }
    },
    {
      "name": "Series details page",
      "contentId": "SERIES_042",
      "mediaType": "series",
      "expect": {
        "element": "DetailsScreen",
        "elementTimeout": 10000,
        "noErrors": true
      }
    },
    {
      "name": "Invalid content ID",
      "contentId": "DOES_NOT_EXIST",
      "mediaType": "movie",
      "expect": {
        "noPlayback": true,
        "noErrors": true
      }
    },
    {
      "name": "Home screen (no content ID)",
      "contentId": "",
      "expect": {
        "element": "HomePage",
        "elementTimeout": 10000
      }
    }
  ]
}

Config file resolution order:

1. Path passed as CLI argument
2. deeplinks.json in cwd
3. .roku-deeplinks.json in cwd
4. roku-deeplink key in package.json

Test case options

| Field | Type | Description | |---|---|---| | name | string | Test name for reports | | contentId | string | Content ID to deep link to (empty string for home) | | mediaType | string? | Media type (movie, series, episode, shortFormVideo, etc.) | | params | object? | Extra key-value params passed to the deep link | | coldStart | boolean? | Force-close the app before deep linking |

Expectations

| Field | Type | Description | |---|---|---| | playback | boolean | Expect media playback to start | | playbackTimeout | number | Max ms to wait for playback (default 15000) | | noPlayback | boolean | Expect playback to NOT be active | | element | string | UI element selector to wait for | | text | string | Text content to wait for (uses element as container) | | focused | string | Element selector that should have focus | | elementTimeout | number | Max ms to wait for element/text/focus (default 10000) | | noErrors | boolean | Check console for BrightScript errors |

CLI

# Run all tests from config
roku-deeplink run ./deeplinks.json --device 192.168.0.30

# Override channel ID
roku-deeplink run ./deeplinks.json --device 192.168.0.30 --channel 12345

# Output formats
roku-deeplink run ./deeplinks.json --format json
roku-deeplink run ./deeplinks.json --format junit

# Save results to file
roku-deeplink run ./deeplinks.json --output results.xml --format junit

# Adjust timing
roku-deeplink run ./deeplinks.json --settle 3000 --timeout 30000

# Skip optional checks
roku-deeplink run ./deeplinks.json --no-home --no-console

# Run a single quick test
roku-deeplink test --content-id MOVIE_001 --media-type movie --expect-playback --device 192.168.0.30

# Generate template config
roku-deeplink init
roku-deeplink init --output my-tests.json

Environment variables

| Variable | Description | |---|---| | ROKU_DEVICE_IP | Default device IP (used when --device is omitted) |

Library API

import { DeepLinkRunner } from '@danecodes/roku-deeplink';

const runner = new DeepLinkRunner('192.168.0.30', {
  channelId: 'dev',
  playbackTimeout: 15000,
  elementTimeout: 10000,
  settleDuration: 2000,
  goHomeBetween: true,
  consoleCheck: true,
});

// Run all tests
const results = await runner.runAll(tests);

// Run a single test
const result = await runner.run({
  name: 'Movie playback',
  contentId: 'MOVIE_001',
  mediaType: 'movie',
  expect: { playback: true },
});

// Format results
console.log(runner.formatReport(results));  // human-readable text
runner.toJSON(results);                     // JSON string
runner.toJUnit(results);                    // JUnit XML string

Config utilities

import { loadConfig, validateConfig, generateTemplate } from '@danecodes/roku-deeplink';

// Load from file (with fallback resolution)
const config = await loadConfig('./deeplinks.json');

// Validate a raw object
const validated = validateConfig(someObject);

// Generate a starter config
const template = generateTemplate();

Test execution flow

For each test case:

1. Go home — closeApp(), wait 1s (skipped if goHomeBetween: false)
2. Deep link — deepLink(channelId, contentId, mediaType)
3. Settle — wait settleDuration ms for the app to load
4. Check expectations in order:
   • playback — poll queryMediaPlayer() until state is "play"
   • noPlayback — verify player is NOT in "play" state
   • element — waitForElement() with the given selector
   • text — waitForText() for content within a container
   • focused — waitForFocus() on the given selector
5. Console check — readConsole() + parseConsoleForIssues(), fail if errors found

If any step fails, the test stops early and reports the failure.

Roku certification context

Roku requires these deep link behaviors for certification:

• App launch must complete within 15 seconds of deep link
• Playback must initiate within 8 seconds of app launch for playable content
• Deep links to invalid content must show an error/fallback, not crash
• Deep links with no content ID should launch to the home screen
• App must handle deep links from cold start and while already running
• Must support contentId and mediaType parameters at minimum

The default timeouts in this tool reflect these requirements. Use the coldStart option on individual test cases to verify both cold and warm start behavior.

CI integration

The CLI exits with code 1 when any test fails, and supports JUnit XML output for CI systems:

roku-deeplink run deeplinks.json --device $ROKU_IP --format junit --output results.xml

License

MIT