@wdio/native-utils

Utilities for WebdriverIO Native Desktop Services.

Overview

This package provides essential utilities for WebdriverIO Native Desktop Services (Electron and Tauri), including configuration management, diagnostics, package handling, and cross-platform executable management.

Features

Configuration Management

Read and parse configuration files (JSON, YAML, TOML) with support for environment variable substitution.

import { readConfig } from '@wdio/native-utils';

const config = await readConfig('./config.json');
// Supports JSON, YAML, and TOML formats

Diagnostics

Comprehensive diagnostic utilities for troubleshooting desktop application issues.

import {
  diagnoseBinary,
  diagnosePlatform,
  diagnoseDisplay,
  formatDiagnosticResults
} from '@wdio/native-utils';

// Check binary paths
const binaryResult = await diagnoseBinary('/path/to/binary');

// Get platform information
const platformInfo = diagnosePlatform();

// Check display capabilities
const displayInfo = await diagnoseDisplay();

// Format results for logging
const formatted = formatDiagnosticResults([binaryResult, platformInfo, displayInfo]);

Package Management

Utilities for reading and working with package.json files.

import { readPackageUp, readPackageUpSync } from '@wdio/native-utils';

// Find and read package.json upward from current directory
const result = readPackageUp();
if (result.ok) {
  console.log('Package name:', result.value.packageJson.name);
}

// Synchronous version
const syncResult = readPackageUpSync();

Result Types

Functional programming style Result types (Ok/Err pattern) for error handling.

import { Ok, Err, isOk, isErr, unwrap, wrapAsync } from '@wdio/native-utils';

// Create successful results
const success = Ok('data');
console.log(isOk(success)); // true

// Create error results
const failure = Err(new Error('Something went wrong'));
console.log(isErr(failure)); // true

// Unwrap with error throwing
const data = unwrap(success); // 'data'
const error = unwrap(failure); // throws Error

// Wrap async functions
const asyncResult = await wrapAsync(() => fetchData());

Executable Management

Cross-platform executable selection and validation.

import { selectExecutable, validateBinaryPaths } from '@wdio/native-utils';

// Select best available executable from options
const executable = selectExecutable(['electron', 'electron.exe'], '/custom/path');

// Validate binary paths
const validation = await validateBinaryPaths(['/path/to/electron', '/path/to/tauri']);

Window Utilities

Utilities for working with application windows.

import { waitUntilWindowAvailable } from '@wdio/native-utils';

// Wait for a window to become available
await waitUntilWindowAvailable('My App Window', { timeout: 5000 });

Logging

Structured logging utilities.

import { createLogger } from '@wdio/native-utils';

const log = createLogger('my-service', 'module-name');
log.info('Application started');
log.error('Something went wrong', error);

API Reference

Configuration

• readConfig(path: string) - Read and parse configuration files

Diagnostics

• diagnoseBinary(path: string) - Check binary file information
• diagnosePlatform() - Get platform-specific information
• diagnoseDisplay() - Check display capabilities
• diagnoseDiskSpace(path?: string) - Check available disk space
• diagnoseLinuxDependencies() - Check Linux system dependencies
• diagnoseSharedLibraries(binaryPath: string) - Check shared library dependencies
• formatDiagnosticResults(results: DiagnosticResult[]) - Format diagnostic results

Package Management

• readPackageUp(options?: ReadPackageUpOptions) - Find and read package.json upward
• readPackageUpSync(options?: ReadPackageUpOptions) - Synchronous version

Result Types

• Ok<T>(value: T) - Create successful result
• Err<E>(error: E) - Create error result
• isOk<T>(result: Result<T, any>) - Check if result is success
• isErr(result: Result<any, any>) - Check if result is error
• unwrap<T>(result: Result<T, any>) - Get value or throw error
• unwrapOr<T>(result: Result<T, any>, defaultValue: T) - Get value or default
• map<T, U>(result: Result<T, any>, fn: (value: T) => U) - Transform success value
• mapErr<T, E, F>(result: Result<T, E>, fn: (error: E) => F) - Transform error value
• wrapAsync<T>(fn: () => Promise<T>) - Wrap async function in Result

Executable Management

• selectExecutable(candidates: string[], customPath?: string) - Select best executable
• validateBinaryPaths(paths: string[]) - Validate multiple binary paths

Window Management

• waitUntilWindowAvailable(windowTitle: string, options?: { timeout?: number }) - Wait for window

Logging

• createLogger(name: string, area?: string) - Create structured logger

License

MIT