0
# Sauce Labs Integration
1

2
Advanced integration features for Sauce Labs test execution including job link generation and authentication.
3

4
## Capabilities
5

6
### Test Link Generation
7

8
Generate Sauce Labs job URLs with optional sharable authentication tokens.
9

10
```typescript { .api }
11
/**
12
 * Generate Sauce Labs job URLs for test sessions
13
 * Creates links to view test results in Sauce Labs dashboard
14
 * @param options - Test link configuration with capabilities and session info
15
 * @returns Array of formatted job link strings (empty if not applicable)
16
 */
17
getTestLink(options: TestLink): string[];
18

19
interface TestLink {
20
  /** Browser capabilities and configuration */
21
  capabilities: Capabilities.ResolvedTestrunnerCapabilities;
22
  /** WebDriver session ID */
23
  sessionId: string;
24
  /** Whether using multiremote setup */
25
  isMultiremote: boolean;
26
  /** Name of multiremote instance (optional) */
27
  instanceName?: string;
28
}
29
```
30

31
**Usage Examples:**
32

33
```typescript
34
import SpecReporter from "@wdio/spec-reporter";
35

36
const reporter = new SpecReporter({
37
  sauceLabsSharableLinks: true
38
});
39

40
// Single browser test link
41
const link = reporter.getTestLink({
42
  capabilities: {
43
    browserName: 'chrome',
44
    browserVersion: '91',
45
    platformName: 'Windows 10'
46
  },
47
  sessionId: 'abc123def456',
48
  isMultiremote: false
49
});
50
// Returns: ["Check out job at https://app.saucelabs.com/tests/abc123def456?auth=token123"]
51

52
// Multiremote test links
53
const multiLinks = reporter.getTestLink({
54
  capabilities: {
55
    browserA: { browserName: 'chrome' },
56
    browserB: { browserName: 'firefox' }
57
  },
58
  sessionId: 'def456ghi789',
59
  isMultiremote: true,
60
  instanceName: 'browserA'
61
});
62
// Returns: ["Check out browserA job at https://app.saucelabs.com/tests/def456ghi789?auth=token456"]
63

64
// Real Device Cloud (RDC) link from capabilities
65
const rdcLink = reporter.getTestLink({
66
  capabilities: {
67
    'appium:deviceName': 'iPhone 12',
68
    testobject_test_report_url: 'https://app.eu-central-1.saucelabs.com/tests/xyz789'
69
  },
70
  sessionId: 'xyz789abc123',
71
  isMultiremote: false
72
});
73
// Returns: ["Check out job at https://app.eu-central-1.saucelabs.com/tests/xyz789"]
74
```
75

76
### Sharable Links Configuration
77

78
Control whether Sauce Labs job links include authentication tokens for public access.
79

80
```typescript { .api }
81
interface SharableLinkOptions {
82
  /**
83
   * Enable/disable Sauce Labs sharable links
84
   * When true, generates links that can be viewed by anyone
85
   * When false, generates standard team-only links
86
   * @default true
87
   */  
88
  sauceLabsSharableLinks: boolean;
89
}
90
```
91

92
**Usage Examples:**
93

94
```typescript
95
// Enable sharable links (default)
96
const reporter = new SpecReporter({
97
  sauceLabsSharableLinks: true
98
});
99
// Generates: https://app.saucelabs.com/tests/session123?auth=abcdef123456
100

101
// Disable sharable links (team-only access)
102
const teamOnlyReporter = new SpecReporter({
103
  sauceLabsSharableLinks: false  
104
});
105
// Generates: https://app.saucelabs.com/tests/session123
106

107
// WebdriverIO configuration
108
export const config = {
109
  reporters: [
110
    ['spec', {
111
      sauceLabsSharableLinks: false // Disable public sharing
112
    }]
113
  ]
114
};
115
```
116

117
### Authentication Token Generation
118

119
Utility function for generating Sauce Labs authentication tokens.
120

121
```typescript { .api }
122
/**
123
 * Generate Sauce Labs authentication token for sharable links
124
 * Creates HMAC-MD5 token using username, access key, and session ID
125
 * @param user - Sauce Labs username
126
 * @param key - Sauce Labs access key  
127
 * @param sessionId - WebDriver session ID
128
 * @returns Authentication query parameter string
129
 */
130
function sauceAuthenticationToken(user: string, key: string, sessionId: string): string;
131
```
132

133
**Usage Examples:**
134

135
```typescript
136
import { sauceAuthenticationToken } from "@wdio/spec-reporter";
137

138
// Generate authentication token
139
const token = sauceAuthenticationToken(
140
  'myusername',
141
  'my-access-key-123',
142
  'session-abc-123'
143
);
144
// Returns: "?auth=a1b2c3d4e5f6..."
145

146
// Full URL construction
147
const sessionId = 'abc123def456';
148
const baseUrl = 'https://app.saucelabs.com/tests/';
149
const authToken = sauceAuthenticationToken('user', 'key', sessionId);
150
const fullUrl = `${baseUrl}${sessionId}${authToken}`;
151
// Result: "https://app.saucelabs.com/tests/abc123def456?auth=a1b2c3d4e5f6..."
152
```
153

154
### Regional Data Center Support
155

156
Automatic URL generation for different Sauce Labs data centers.
157

158
```typescript { .api }
159
interface DataCenterConfig {
160
  /** Sauce Labs hostname indicating data center */
161
  hostname: string;
162
  /** Region configuration (us-east-4, eu-central-1, etc.) */
163
  region?: string;
164
  /** Sauce Labs username */
165
  user: string;
166
  /** Sauce Labs access key */
167
  key: string;
168
}
169
```
170

171
**Usage Examples:**
172

173
```typescript
174
// US West (default)
175
const usWestConfig = {
176
  hostname: 'ondemand.saucelabs.com',
177
  user: 'myuser',
178
  key: 'mykey'
179
};
180
// Generates: https://app.saucelabs.com/tests/...
181

182
// US East 4
183
const usEast4Config = {
184
  hostname: 'ondemand.us-east-4.saucelabs.com',
185
  user: 'myuser', 
186
  key: 'mykey'
187
};
188
// Generates: https://app.us-east-4.saucelabs.com/tests/...
189

190
// EU Central 1  
191
const euConfig = {
192
  hostname: 'ondemand.eu-central-1.saucelabs.com',
193
  user: 'myuser',
194
  key: 'mykey'
195
};
196
// Generates: https://app.eu-central-1.saucelabs.com/tests/...
197

198
// Via region property
199
const regionConfig = {
200
  hostname: 'ondemand.saucelabs.com',
201
  region: 'eu-central-1',
202
  user: 'myuser',
203
  key: 'mykey'  
204
};
205
// Generates: https://app.eu-central-1.saucelabs.com/tests/...
206
```
207

208
### Mobile Device Support
209

210
Special handling for Real Device Cloud (RDC) and mobile testing.
211

212
```typescript { .api }
213
interface MobileCapabilities {
214
  /** Direct RDC test report URL from capabilities */
215
  testobject_test_report_url?: string;
216
  /** Mobile device name */
217
  'appium:deviceName'?: string;
218
  /** Mobile platform version */
219
  'appium:platformVersion'?: string;
220
  /** Mobile platform name */
221
  'appium:platformName'?: string;
222
}
223
```
224

225
**Usage Examples:**
226

227
```typescript
228
// Real Device Cloud with direct URL
229
const rdcCapabilities = {
230
  'appium:deviceName': 'iPhone 12',
231
  'appium:platformVersion': '14.5',
232
  'appium:platformName': 'iOS',
233
  testobject_test_report_url: 'https://app.eu-central-1.saucelabs.com/tests/mobile123'
234
};
235

236
const rdcLink = reporter.getTestLink({
237
  capabilities: rdcCapabilities,
238
  sessionId: 'mobile123',
239
  isMultiremote: false
240
});
241
// Returns: ["Check out job at https://app.eu-central-1.saucelabs.com/tests/mobile123"]
242

243
// Virtual Device Cloud (VDC) 
244
const vdcCapabilities = {
245
  'appium:deviceName': 'Android GoogleAPI Emulator',
246
  'appium:platformVersion': '11.0',
247
  'appium:platformName': 'Android',
248
  browserName: 'Chrome'
249
};
250
// Uses standard VDC URL construction with authentication tokens
251
```
252

253
### Multiremote Integration
254

255
Support for multiple browser instances in a single test session.
256

257
```typescript { .api }
258
interface MultiremoteTestLink extends TestLink {
259
  /** Whether this is a multiremote test setup */
260
  isMultiremote: true;
261
  /** Name of the specific browser instance */
262
  instanceName: string;
263
  /** Capabilities object containing multiple browser configs */
264
  capabilities: {
265
    [instanceName: string]: Capabilities.ResolvedTestrunnerCapabilities;
266
  };
267
}
268
```
269

270
**Usage Examples:**
271

272
```typescript
273
const reporter = new SpecReporter({});
274

275
// Multiremote configuration generates separate links for each browser
276
const multiremoteCapabilities = {
277
  chrome: {
278
    browserName: 'chrome',
279
    browserVersion: '91',
280
    sessionId: 'chrome-session-123'
281
  },
282
  firefox: {
283
    browserName: 'firefox', 
284
    browserVersion: '89',
285
    sessionId: 'firefox-session-456'
286
  }
287
};
288

289
// Link for Chrome instance
290
const chromeLink = reporter.getTestLink({
291
  capabilities: multiremoteCapabilities,
292
  sessionId: 'chrome-session-123',
293
  isMultiremote: true,
294
  instanceName: 'chrome'
295
});
296
// Returns: ["Check out chrome job at https://app.saucelabs.com/tests/chrome-session-123?auth=..."]
297

298
// Link for Firefox instance  
299
const firefoxLink = reporter.getTestLink({
300
  capabilities: multiremoteCapabilities,
301
  sessionId: 'firefox-session-456',
302
  isMultiremote: true,
303
  instanceName: 'firefox'
304
});
305
// Returns: ["Check out firefox job at https://app.saucelabs.com/tests/firefox-session-456?auth=..."]
306
```
307

308
### Link Display in Reports
309

310
Sauce Labs links are automatically included in test reports when applicable.
311

312
```typescript
313
// Example report output with Sauce Labs links:
314
// ------------------------------------------------------------------
315
// [chrome 91 Windows 10 #0-0] Running: chrome (v91) on Windows 10
316
// [chrome 91 Windows 10 #0-0] Session ID: abc123def456
317
// [chrome 91 Windows 10 #0-0]
318
// [chrome 91 Windows 10 #0-0] » /tests/login.test.js
319
// [chrome 91 Windows 10 #0-0] Login Tests
320
// [chrome 91 Windows 10 #0-0]    ✓ should display login form
321
// [chrome 91 Windows 10 #0-0]    ✓ should authenticate valid user
322
// [chrome 91 Windows 10 #0-0]
323
// [chrome 91 Windows 10 #0-0] 2 passing (3.2s)
324
// [chrome 91 Windows 10 #0-0]
325
// [chrome 91 Windows 10 #0-0] Check out job at https://app.saucelabs.com/tests/abc123def456?auth=xyz789
326
```