Skip to content

Commit 076bf4d

Browse files
Ishavyas9Ishavyas9
authored
Merge pull request LambdaTest#1874 from Ishavyas9/DocStage
Playwright SDK doc
2 parents 4e3134e + 771f257 commit 076bf4d

File tree

2 files changed

+228
-0
lines changed

2 files changed

+228
-0
lines changed

‎docs/playwright-sdk.md‎

Lines changed: 222 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,222 @@
1+
---
2+
id: playwright-sdk
3+
title: Playwright SDK
4+
sidebar_label: Playwright SDK
5+
description: A guide to getting started with the Playwright-Node.js SDK by LambdaTest.
6+
keywords:
7+
- playwright
8+
- nodejs
9+
- sdk
10+
- lambdatest
11+
- automation
12+
- testing
13+
slug: /playwright-sdk/
14+
---
15+
16+
import Tabs from '@theme/Tabs';
17+
import TabItem from '@theme/TabItem';
18+
19+
This document guides you through setting up and using the LambdaTest Playwright-Node.js SDK to run your Playwright tests on the LambdaTest platform.
20+
21+
## Overview
22+
The LambdaTest Playwright Node SDK is a command-line interface (CLI) tool designed to streamline the process of running your existing Playwright tests on the LambdaTest cloud grid. It eliminates the need for code modifications and provides a simple, configuration-driven approach to test execution.
23+
24+
Key benefits include:
25+
26+
* **Effortless Execution**: Run your entire test suite on the LambdaTest platform with a single, simple command. The SDK handles all the underlying complexity of connecting to the grid.
27+
* **Zero Code Changes**: Integrate your existing Playwright tests without modifying your test scripts. All configuration is managed externally in the lambdatest.yml file.
28+
* **Centralized Capabilities**: Define and manage all your test environments—including browser, platform, and resolution combinations—in a single, easy-to-read YAML file.
29+
* **Local & Private Testing**: Seamlessly test internal, pre-production, or locally hosted websites using the LambdaTest Tunnel, which can be managed automatically by the SDK.
30+
* **CI/CD Integration**: The command-line nature of the SDK makes it trivial to integrate into any CI/CD pipeline (like Jenkins, GitHub Actions, CircleCI, etc.) for continuous testing.
31+
* **Rich Test Artifacts**: All test runs are automatically reported to your LambdaTest Dashboard, complete with video recordings, step-by-step screenshots, browser logs, and network logs for easy debugging.
32+
33+
## Prerequisites
34+
35+
Before proceeding, ensure the following requirements are met:
36+
37+
* A LambdaTest account. A free account can be created at [LambdaTest - AI Powered Testing Tool | AI Testing Agents On Cloud](https://www.lambdatest.com/signup).
38+
* Your LambdaTest username and access key, which are available in your [LambdaTest profile](https://accounts.lambdatest.com/detail/profile).
39+
* A local installation of Node.js and npm.
40+
* An existing Playwright project.
41+
42+
## Installation
43+
44+
To get started, install the SDK as a development dependency within your project's root directory.
45+
46+
```bash
47+
npm install @lambdatest/playwright-node-sdk
48+
```
49+
50+
## Configuration
51+
52+
The SDK is configured via a `lambdatest.yml` file located in your project root. This YAML file orchestrates your test execution, defining credentials, capabilities, and other run settings.
53+
54+
### 1. Initializing the Configuration File
55+
56+
You can generate a template `lambdatest.yml` file by running the following command. You may also provide an optional filename.
57+
58+
```bash
59+
npx playwright-node-sdk --init [(optional: filename)]
60+
```
61+
62+
Below is the structure and explanation of the configuration options available in the `lambdatest.yml` file.
63+
64+
```yaml
65+
# Access your LambdaTest credentials from https://accounts.lambdatest.com/security/username-accesskey
66+
# It's recommended to use environment variables for your credentials.
67+
user: {YOUR_LAMBDATEST_USERNAME}
68+
accessKey: {YOUR_LAMBDATEST_ACCESS_KEY}
69+
70+
# Build name for your test run
71+
build: "Playwright Node.js SDK Build"
72+
73+
# Name of the test suite
74+
name: "Playwright Test Suite"
75+
76+
# Global base configuration
77+
framework: "playwright" # Framework name
78+
source: "node-js-playwright-sample-sdk:v1" # GitHub branch and tag
79+
80+
# Optional: Build and project tags for organization and filtering
81+
buildTags: ["playwright", "nodejs", "typescript"]
82+
tags: ["smoke", "regression"]
83+
projectName: "Playwright Node SDK Testing"
84+
85+
# Define the number of parallel sessions for each configuration
86+
# Check your parallel session limits at https://billing.lambdatest.com/billing/subscriptions
87+
parallelsPerPlatform: 2
88+
89+
# Optional: Advanced settings applied to all tests
90+
network: false # To capture network HAR logs (may impact test execution speed)
91+
console: false # To capture browser console logs (may impact test execution speed)
92+
video: true # To capture video for debugging (may impact test execution speed)
93+
tunnel: false # To test pages behind a VPN/private network or from a local system. Refer to https://www.lambdatest.com/support/docs/testing-locally-hosted-pages/
94+
dedicatedProxy: false
95+
idleTimeout: 300
96+
timezone: "UTC"
97+
visual: true # To capture a screenshot for each command (may impact test execution speed)
98+
headless: false # To run tests in headless mode. Note: Video will not be available for headless tests.
99+
commandLog: true # To capture commands that are executed on the LambdaTest platform
100+
resolution: "1280x960" # To set the global resolution/viewport size to execute tests
101+
102+
# Tunnel-specific tests
103+
tunnel_settings:
104+
# tunnel: true
105+
# autostart: true
106+
# tunnelName: "app-behind-firewall-localhost-test-tunnel"
107+
# localdirectory: "./log"
108+
# verbose: true
109+
# loglevel: "debug"
110+
111+
# Global Playwright configuration (inherited by all platforms unless overridden)
112+
playwrightConfigOptions:
113+
testDir: "tests"
114+
# use:
115+
# viewport: { width: 1280, height: 720 }
116+
117+
# Refer to the capability generator for detailed configurations: https://www.lambdatest.com/capabilities-generator/
118+
platforms:
119+
- platform: "macOS Sequoia" # Or "Windows 11", "android", "ios"
120+
browserName: "chrome" # Or "firefox", "safari"
121+
# You can specify an exact browser version or use "latest", "latest-1", etc.
122+
browserVersion: "latest"
123+
# For mobile testing
124+
# deviceName: "Pixel 7" # Or "iPhone 14"
125+
# platformVersion: "13" # Or "16"
126+
# isRealMobile: true
127+
# ltOptions:
128+
# Geolocation-specific tests
129+
# geoLocation: "GB"
130+
# Network communication tests (enable network logging)
131+
# network: true
132+
# console: true
133+
# fullHar: true # To capture request and response body (might slow the test execution)
134+
# playwrightConfigOptions:
135+
# testDir: "additional-tests"
136+
# testMatch: ["**/mobile-responsive.spec.ts"]
137+
# # For mobile testing
138+
# use:
139+
# viewport: { width: 390, height: 844 }
140+
```
141+
142+
### 2. Credentials Configuration
143+
144+
In the `lambdatest.yml` file, replace the placeholder values for `user` and `accessKey` with your LambdaTest credentials.
145+
146+
### 3. Platform Configuration
147+
148+
The `platforms` array defines the target environments (OS/browser combinations) for your test execution. You can specify multiple platform objects. For a complete list of valid platform configurations, consult the [LambdaTest Capabilities Generator](https://www.lambdatest.com/capabilities-generator/).
149+
150+
### 4. Run Settings
151+
152+
The `run_settings` section is not explicitly present in the provided YAML, but you can control test execution behavior by passing standard Playwright CLI arguments directly to the `playwright-node-sdk` command.
153+
154+
### 5. Playwright Project Options
155+
156+
The `playwrightConfigOptions` section provides a powerful mechanism to override your project's native Playwright configuration for the LambdaTest run. This allows for dynamic adjustments without altering your source `playwright.config.js`.
157+
158+
* **testDir**: Specifies the location of your test files.
159+
160+
```yaml
161+
playwrightConfigOptions:
162+
testDir: './tests'
163+
```
164+
165+
* **testMatch** and **testIgnore**: Defines glob patterns to include or exclude specific test files from the run.
166+
167+
```yaml
168+
playwrightConfigOptions:
169+
testMatch: /.*\.e2e\.js/
170+
testIgnore: /.*\.spec\.js/
171+
```
172+
173+
* **setup** and **teardown**: Specifies scripts to be executed before and after your test suite.
174+
175+
```yaml
176+
playwrightConfigOptions:
177+
setup:
178+
- name: 'setup1'
179+
testMatch: '**/*.setup.ts'
180+
teardown: 'teardown1'
181+
teardown:
182+
- name: 'teardown1'
183+
testMatch: '/teardown\.ts/'
184+
```
185+
186+
* **use**: Sets global options that are applied to all tests within the run.
187+
188+
```yaml
189+
playwrightConfigOptions:
190+
use:
191+
baseURL: 'https://www.example.com'
192+
```
193+
194+
### 6. Tunnel Configuration
195+
196+
The `tunnel_settings` section is used for testing applications that are not publicly accessible (e.g., on localhost or behind a firewall).
197+
198+
* **tunnel: true**: Enables the LambdaTest Tunnel feature.
199+
* **autostart: true**: Instructs the SDK to automatically manage the tunnel's lifecycle (start and stop).
200+
201+
## Running Your Tests
202+
203+
To execute your tests on the LambdaTest platform, you will use the `playwright-node-sdk` CLI wrapper followed by the standard `playwright test` command.
204+
205+
```bash
206+
npx playwright-node-sdk playwright test --config Optional path-of-config.yml
207+
```
208+
209+
### Execution Workflow
210+
211+
When this command is run, the SDK performs the following steps:
212+
213+
1. Reads and parses the `lambdatest.yml` configuration file.
214+
2. If `tunnel: true` and `autostart: true` are set, it establishes a secure connection via the LambdaTest Tunnel.
215+
3. Generates a temporary, in-memory Playwright configuration that includes the necessary hooks to connect to the LambdaTest grid.
216+
4. Executes your Playwright tests using this temporary configuration.
217+
5. Upon test completion, it terminates the LambdaTest Tunnel (if started) and cleans up any temporary artifacts.
218+
219+
You can pass any standard Playwright CLI options directly to this command. For instance, to run a specific test file:
220+
221+
```bash
222+
npx playwright-node-sdk playwright test tests/my-test.spec.js

‎sidebars.js‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2513,6 +2513,11 @@ module.exports = {
25132513
label: "Playwright Testing ",
25142514
items: ["playwright-testing-guide"],
25152515
},
2516+
{
2517+
type: "doc",
2518+
id: "playwright-sdk",
2519+
label: "Playwright SDK",
2520+
},
25162521
{
25172522
type: "category",
25182523
collapsed: true,
@@ -2532,6 +2537,7 @@ module.exports = {
25322537
"javascript-with-playwright",
25332538
"jest-with-playwright",
25342539
"typescript-with-playwright",
2540+
"playwright-sdk"
25352541
],
25362542
},
25372543
{

0 commit comments

Comments
 (0)