Skip to content

HARDWARE_TESTING.md

Latest commit

 

History

History
134 lines (97 loc) · 2.91 KB

HARDWARE_TESTING.md

File metadata and controls

134 lines (97 loc) · 2.91 KB

Hardware Testing Environment

This document explains how to set up and run hardware tests for Trezor and Ledger devices.

Prerequisites

  • Trezor Device: Model T, One, or newer
  • Trezor Bridge: Required for USB communication
  • Node.js: Version 16.20.1 or higher

Quick Start

Option 1: Automated Setup (Recommended)

Use the provided setup script to automatically install dependencies and configure your environment:

# Run the automated setup script
./scripts/setup-hw-testing.sh

This script will:

  • Install Trezor Bridge automatically
  • Set up udev rules (Linux only)
  • Create necessary directories
  • Make all scripts executable

Option 2: Manual Setup

1. Install Trezor Bridge

Using the installation script:

./scripts/install-trezor-bridge.sh

Or manually:

macOS:

brew install trezor-suite

Linux:

# Download from https://suite.trezor.io/trezor-bridge
# Or use your package manager

Windows:

2. Start Trezor Bridge

# Start Trezor Bridge
trezord

3. Run Tests

# Run tests with your physical Trezor device
yarn test:hw:trezor

Available Test Commands

Command Description
yarn test:hw:trezor Run Trezor hardware tests
yarn test:hw:ledger Run Ledger hardware tests

Test Structure

Hardware tests are located in:

  • test/hardware/trezor/ - Trezor-specific tests
  • test/hardware/ledger/ - Ledger-specific tests

Troubleshooting

Common Issues

"Trezor transport failed"

  • Ensure Trezor Bridge is running: trezord
  • Check device connection
  • Verify device is unlocked

"No Trezor device connected/unlocked"

  • Connect your Trezor device via USB
  • Unlock the device using your PIN
  • Ensure no other applications are using the device

"Authentication failure"

  • Unlock your Trezor device
  • Close other applications using the device
  • Try reconnecting the device

Security Notes

  • Never use real hardware devices in CI/CD
  • Physical devices should only be used in secure development environments
  • Always verify device authenticity before use

Development

Adding New Tests

  1. Create test files in test/hardware/trezor/ or test/hardware/ledger/
  2. Use the existing test patterns
  3. Ensure tests work with physical devices

Test Patterns

import { TrezorKeyAgent } from '@cardano-sdk/hardware-trezor';

describe('TrezorKeyAgent', () => {
  it('should work with hardware device', async () => {
    const keyAgent = await TrezorKeyAgent.createWithDevice({
      chainId: Cardano.ChainIds.Preprod,
      trezorConfig: {
        communicationType: CommunicationType.Node,
        manifest: {
          appUrl: 'https://your-app.com',
          email: 'contact@your-app.com'
        }
      }
    }, dependencies);
    
    // Test your functionality
  });
});
⚡