@browserstack/wdio-browserstack-service

Core SDK for BrowserStack integration used by the WebdriverIO BrowserStack Service. For user configuration and service options, see the official service README: https://github.com/webdriverio/webdriverio/blob/main/packages/wdio-browserstack-service/README.md

Table of Contents

1. Overview
2. Code Generation
3. Development
4. Contributing
5. License

Overview

This package provides the TypeScript-based gRPC client and Protobuf definitions used internally by the @wdio/browserstack-service plugin for WebdriverIO. It includes:

• Generated TypeScript types and clients from Protobuf definitions.
• Message factory constructors for backward compatibility.

Installation

This module is included as a dependency of the @wdio/browserstack-service package. Users should install and configure the service as documented in the linked README above.

Setup & Configuration

Add the service to your WebdriverIO configuration (wdio.conf.js):

export BROWSERSTACK_USERNAME=your_username
export BROWSERSTACK_ACCESS_KEY=your_access_key

Usage

Import and use the gRPC client and message constructors:

import { SDKClient, StartBinSessionRequestConstructor } from '@browserstack/wdio-browserstack-service';
import path from 'path';
import process from 'process';
import { CLIUtils } from '@browserstack/cli-utils'; // example import, adjust if needed
import { version as packageVersion } from './package.json'; // adjust to your setup

// Initialize the client (uses default insecure credentials unless overridden)
const client = new SDKClient('grpc.browserstack.com:443');

// Collect framework details
const automationFrameworkDetail = CLIUtils.getAutomationFrameworkDetail();
const testFrameworkDetail = CLIUtils.getTestFrameworkDetail();

const frameworkVersions = {
  ...automationFrameworkDetail.version,
  ...testFrameworkDetail.version
};

// Build StartBinSessionRequest
const startReq = StartBinSessionRequestConstructor.create({
  binSessionId: 'your-session-id', // replace with actual session id
  sdkLanguage: CLIUtils.getSdkLanguage(),
  sdkVersion: packageVersion,
  pathProject: process.cwd(),
  pathConfig: path.resolve(process.cwd(), 'browserstack.yml'),
  cliArgs: process.argv.slice(2),
  frameworks: [automationFrameworkDetail.name, testFrameworkDetail.name],
  frameworkVersions,
  language: CLIUtils.getSdkLanguage(),
  testFramework: testFrameworkDetail.name,
  wdioConfig: {}, // provide your WDIO config if applicable
});

// Start a session
client.startBinSession(startReq).then(response => {
  console.log('Started session:', response.binSessionId);
}).catch(err => {
  console.error('Failed to start session:', err);
});

Code Generation

This project uses Buf and ts-proto to generate TypeScript code from Protobuf definitions.

Prerequisites

• Buf CLI
• Node.js ≥16

Generate & Build

# Clean previously generated files
npm run clean

# Generate from .proto files
npm run generate

# Compile to JS and declaration files
npm run build

Generated files appear under dist/ and should be published to npm.

Development

Clone the repository and install dependencies:

git clone https://github.com/browserstack/wdio-browserstack-service.git
cd wdio-browserstack-service
npm install

Run generation and build:

npm run build

Contributing

Contributions are welcome! Please open issues or pull requests in the GitHub repository.

License

MIT © BrowserStack