Skip to content

Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.

docs: update step.skip docs after api review (#34968)

Dmitry Gozman934e123d1b12
diff --git a/docs/src/test-api/class-test.md b/docs/src/test-api/class-test.md
index a719ee6bd5..9384ac61b9 100644
--- a/docs/src/test-api/class-test.md
+++ b/docs/src/test-api/class-test.md
@@ -1773,6 +1773,8 @@ Specifies a custom location for the step to be shown in test reports and trace v
Mark a test step as "skip" to temporarily disable its execution, useful for steps that are currently failing and planned for a near-term fix. Playwright will not run the step.
+We recommend [`method: TestStepInfo.skip#1`] instead.
+
**Usage**
You can declare a skipped step, and Playwright will not run it.
diff --git a/docs/src/test-api/class-teststepinfo.md b/docs/src/test-api/class-teststepinfo.md
index f4bba6232b..f13632a776 100644
--- a/docs/src/test-api/class-teststepinfo.md
+++ b/docs/src/test-api/class-teststepinfo.md
@@ -83,12 +83,41 @@ Path on the filesystem to the attached file. Mutually exclusive with [`option: b
## method: TestStepInfo.skip#1
* since: v1.51
-Unconditionally skip the currently running step. Test step is immediately aborted. This is similar to [`method: Test.step.skip`].
+Abort the currently running step and mark it as skipped. Useful for steps that are currently failing and planned for a near-term fix.
+
+**Usage**
+
+```js
+import { test, expect } from '@playwright/test';
+
+test('my test', async ({ page }) => {
+ await test.step('check expectations', async () => {
+ test.skip();
+ // step body below will not run
+ // ...
+ });
+});
+```
## method: TestStepInfo.skip#2
* since: v1.51
-Conditionally skips the currently running step with an optional description. This is similar to [`method: Test.step.skip`].
+Conditionally skip the currently running step with an optional description. Useful for steps that should not be executed in some cases.
+
+**Usage**
+
+```js
+import { test, expect } from '@playwright/test';
+
+test('my test', async ({ page, isMobile }) => {
+ await test.step('check desktop expectations', async () => {
+ test.skip(isMobile, 'not present in the mobile layout');
+
+ // step body below will not run
+ // ...
+ });
+});
+```
### param: TestStepInfo.skip#2.condition
* since: v1.51
diff --git a/packages/playwright/types/test.d.ts b/packages/playwright/types/test.d.ts
index d9f54a5e1a..c1f01a182e 100644
--- a/packages/playwright/types/test.d.ts
+++ b/packages/playwright/types/test.d.ts
@@ -5800,6 +5800,9 @@ export interface TestType<TestArgs extends {}, WorkerArgs extends {}> {
* Mark a test step as "skip" to temporarily disable its execution, useful for steps that are currently failing and
* planned for a near-term fix. Playwright will not run the step.
*
+ * We recommend [testStepInfo.skip()](https://playwright.dev/docs/api/class-teststepinfo#test-step-info-skip-1)
+ * instead.
+ *
* **Usage**
*
* You can declare a skipped step, and Playwright will not run it.
@@ -9658,14 +9661,45 @@ export interface TestStepInfo {
}): Promise<void>;
/**
- * Unconditionally skip the currently running step. Test step is immediately aborted. This is similar to
- * [test.step.skip(title, body[, options])](https://playwright.dev/docs/api/class-test#test-step-skip).
+ * Abort the currently running step and mark it as skipped. Useful for steps that are currently failing and planned
+ * for a near-term fix.
+ *
+ * **Usage**
+ *
+ * ```js
+ * import { test, expect } from '@playwright/test';
+ *
+ * test('my test', async ({ page }) => {
+ * await test.step('check expectations', async () => {
+ * test.skip();
+ * // step body below will not run
+ * // ...
+ * });
+ * });
+ * ```
+ *
*/
skip(): void;
/**
- * Conditionally skips the currently running step with an optional description. This is similar to
- * [test.step.skip(title, body[, options])](https://playwright.dev/docs/api/class-test#test-step-skip).
+ * Conditionally skip the currently running step with an optional description. Useful for steps that should not be
+ * executed in some cases.
+ *
+ * **Usage**
+ *
+ * ```js
+ * import { test, expect } from '@playwright/test';
+ *
+ * test('my test', async ({ page, isMobile }) => {
+ * await test.step('check desktop expectations', async () => {
+ * test.skip(isMobile, 'not present in the mobile layout');
+ *
+ * // step body below will not run
+ * // ...
+ * });
+ * });
+ * ```
+ *
* @param condition A skip condition. Test step is skipped when the condition is `true`.
* @param description Optional description that will be reflected in a test report.
*/