@danecodes/roku-cert

Roku certification preflight checker. Runs automatable certification checks against a Roku device and produces a report before you submit to Roku.

Install

npm install @danecodes/roku-cert

Quick Start

# Full certification preflight
roku-cert run --device 192.168.0.30 --channel dev

# Single check
roku-cert check app_launch_time --device 192.168.0.30

# List all checks
roku-cert checks

CLI

# Run all checks
roku-cert run

# Run with options
roku-cert run --device 192.168.0.30 --channel dev

# Run a specific category
roku-cert run --category launch
roku-cert run --category navigation
roku-cert run --category playback
roku-cert run --category stability

# Run a single check
roku-cert check app_launch_time
roku-cert check trick_play

# Skip checks (non-video apps can skip playback)
roku-cert run --skip playback_initiation,trick_play,playback_error_handling

# With deep link config
roku-cert run --deeplinks ./deeplinks.json

# Output formats
roku-cert run --format text        # default, colorful terminal output
roku-cert run --format json
roku-cert run --format junit       # for CI integration
roku-cert run --format markdown    # for PRs / docs

# Save report to file
roku-cert run --output report.json --format json
roku-cert run --output report.xml --format junit

# Quick single-purpose commands
roku-cert launch-time              # just test launch time
roku-cert cpu                      # just sample CPU for 30s
roku-cert stability                # rapid input + console check

Environment Variables

• ROKU_DEVICE_IP — device IP (alternative to --device)
• ROKU_DEV_PASSWORD — dev password for sideloaded channels

Library API

import { CertRunner } from '@danecodes/roku-cert';

const runner = new CertRunner('192.168.0.30', {
  channelId: 'dev',
  deepLinks: './deeplinks.json',
  launchTimeout: 15000,
  playbackTimeout: 8000,
  cpuThreshold: 80,
  skip: ['playback_initiation', 'trick_play'],
});

// Run all checks
const report = await runner.runAll();

// Run a specific category
const report = await runner.runCategory('launch');

// Run a single check
const result = await runner.runCheck('app_launch_time');

// List available checks
const checks = runner.listChecks();

// Format report
console.log(runner.formatReport(report));  // terminal text
const json = runner.toJSON(report);         // JSON string
const junit = runner.toJUnit(report);       // JUnit XML
const md = runner.toMarkdown(report);       // Markdown

Checks

Launch & Performance

| ID | Check | What it does | |----|-------|-------------| | app_launch_time | App launch time | Cold start, measures time to UI render. Must be <15s. | | relaunch_stability | Relaunch stability | Close and relaunch 3 times. No crashes or console errors. | | cpu_usage | CPU usage | Samples CPU for 30s during idle. Must stay below threshold. | | memory_baseline | Memory baseline | Records memAnon/memFile during idle. Warns if high. |

Navigation & Focus

| ID | Check | What it does | |----|-------|-------------| | back_button | Back button | Navigate forward 3 screens, back 3 times. Must not crash. | | home_exit | Home exit | Press Home from various screens. Must exit cleanly. | | focus_visible | Focus visible | After each nav action, focus must never disappear. | | deep_link_cold | Deep link cold | Deep link with app not running. Delegates to roku-deeplink. | | deep_link_warm | Deep link warm | Deep link with app running. Delegates to roku-deeplink. |

Playback

| ID | Check | What it does | |----|-------|-------------| | playback_initiation | Playback initiation | Verify playback starts within timeout via media player. | | trick_play | Trick play | Pause, resume, rewind, fast forward. Verify state changes. | | playback_error_handling | Error handling | Invalid content ID must show error screen, not crash. |

Stability

| ID | Check | What it does | |----|-------|-------------| | console_idle | No errors idle | Launch, wait 10s, check console for BrightScript errors. | | console_navigation | No errors nav | Navigate 5 screens, check console after each. | | rapid_input | Rapid input | Send 20 keys at 100ms intervals. Must not crash. |

Accessibility

| ID | Check | What it does | |----|-------|-------------| | text_readability | Text readability | Verify key screens have text elements, not just images. |

Report Output

The text formatter produces a terminal report:

╔══════════════════════════════════════════════╗
║  Roku Certification Preflight Report         ║
╠══════════════════════════════════════════════╣
║ Device: Roku Ultra (4800X) — OS 14.0.2       ║
║ Channel: dev                                 ║
║ Date: 2026-04-15                             ║
╚══════════════════════════════════════════════╝

Launch & Performance
────────────────────
✓ App launch time              2.3s (< 15s)
✓ Relaunch stability           3/3 clean
✓ CPU usage                    avg 34% (< 80%)
⚠ Memory baseline              85MB (high but noted)

═══════════════════════════════════════════════
14/15 PASSED | 1 FAILED | 0 SKIPPED
Total time: 2m 14s
═══════════════════════════════════════════════

Exit codes: 0 = all passed, 1 = failures present.

Deep Link Config

Deep link checks use a config file compatible with @danecodes/roku-deeplink:

{
  "channelId": "dev",
  "tests": [
    {
      "name": "Movie playback",
      "contentId": "MOVIE_001",
      "mediaType": "movie",
      "expect": { "playback": true, "noErrors": true }
    }
  ]
}

Non-Video Apps

Skip playback checks for channels without playable content:

roku-cert run --skip playback_initiation,trick_play,playback_error_handling

Or programmatically:

const runner = new CertRunner('192.168.0.30', {
  channelId: 'dev',
  skip: ['playback_initiation', 'trick_play', 'playback_error_handling'],
});

License

MIT