Skip to content

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

feat(test-runner): add test.abort() (#40088)

Pavel Feldman251bbc93a9e1
diff --git a/docs/src/test-api/class-test.md b/docs/src/test-api/class-test.md
index 990c49d873..4992d168c6 100644
--- a/docs/src/test-api/class-test.md
+++ b/docs/src/test-api/class-test.md
@@ -1044,6 +1044,33 @@ An object containing fixtures and/or options. Learn more about [fixtures format]
+## method: Test.abort
+* since: v1.60
+
+Aborts the currently running test by throwing an error. The test is immediately marked as failed and execution stops. This is useful from inside a fixture or a route handler when you have detected an unrecoverable misuse and want to fail the test right away.
+
+**Usage**
+
+```js
+import { test, expect } from '@playwright/test';
+
+test('does not publish to shared page', async ({ page }) => {
+ await page.route('**/publish', route => {
+ test.abort('Tests must not publish to the shared page. Use the `clone` option.');
+ return route.abort();
+ });
+ // ...
+});
+```
+
+### param: Test.abort.message
+* since: v1.60
+- `message` ?<[string]>
+
+Optional message describing the reason for the abort. It will be included in the failure error.
+
+
+
## method: Test.fail
* since: v1.10
diff --git a/packages/playwright/src/common/testType.ts b/packages/playwright/src/common/testType.ts
index 3d91e74152..7b0e0f2b3b 100644
--- a/packages/playwright/src/common/testType.ts
+++ b/packages/playwright/src/common/testType.ts
@@ -55,6 +55,7 @@ export class TestTypeImpl {
test.skip = wrapFunctionWithLocation(this._modifier.bind(this, 'skip'));
test.fixme = wrapFunctionWithLocation(this._modifier.bind(this, 'fixme'));
test.fail = wrapFunctionWithLocation(this._modifier.bind(this, 'fail'));
+ test.abort = wrapFunctionWithLocation(this._abort.bind(this));
test.fail.only = wrapFunctionWithLocation(this._createTest.bind(this, 'fail.only'));
test.slow = wrapFunctionWithLocation(this._modifier.bind(this, 'slow'));
test.setTimeout = wrapFunctionWithLocation(this._setTimeout.bind(this));
@@ -240,6 +241,13 @@ export class TestTypeImpl {
testInfo._modifier(type, location, modifierArgs as [any, any]);
}
+ private _abort(location: Location, message?: string) {
+ const testInfo = currentTestInfo();
+ if (!testInfo)
+ throw new Error(`test.abort() can only be called inside a test or fixture`);
+ testInfo._abort(location, message);
+ }
+
private _setTimeout(location: Location, timeout: number) {
const suite = currentlyLoadingFileSuite();
if (suite) {
diff --git a/packages/playwright/src/worker/testInfo.ts b/packages/playwright/src/worker/testInfo.ts
index 54863e93cb..0f29001550 100644
--- a/packages/playwright/src/worker/testInfo.ts
+++ b/packages/playwright/src/worker/testInfo.ts
@@ -396,6 +396,11 @@ export class TestInfoImpl implements TestInfo {
return step;
}
+ _abort(location: Location, message: string | undefined) {
+ this.annotations.push({ type: 'abort', description: message, location });
+ throw new TestAbortError('Test aborted' + (message ? ': ' + message : ''));
+ }
+
_interrupt() {
// Mark as interrupted so we can ignore TimeoutError thrown by interrupt() call.
this._interruptedPromise.resolve();
@@ -711,6 +716,9 @@ export class TestStepInfoImpl implements TestStepInfo {
export class TestSkipError extends Error {
}
+export class TestAbortError extends Error {
+}
+
export class StepSkipError extends Error {
}
diff --git a/packages/playwright/types/test.d.ts b/packages/playwright/types/test.d.ts
index 1f16509416..721f047330 100644
--- a/packages/playwright/types/test.d.ts
+++ b/packages/playwright/types/test.d.ts
@@ -5531,6 +5531,29 @@ export interface TestType<TestArgs extends {}, WorkerArgs extends {}> {
only(title: string, details: TestDetails, body: TestBody<TestArgs & WorkerArgs>): void;
}
+ /**
+ * Aborts the currently running test by throwing an error. The test is immediately marked as failed and execution
+ * stops. This is useful from inside a fixture or a route handler when you have detected an unrecoverable misuse and
+ * want to fail the test right away.
+ *
+ * **Usage**
+ *
+ * ```js
+ * import { test, expect } from '@playwright/test';
+ *
+ * test('does not publish to shared page', async ({ page }) => {
+ * await page.route('**\/publish', route => {
+ * test.abort('Tests must not publish to the shared page. Use the `clone` option.');
+ * return route.abort();
+ * });
+ * // ...
+ * });
+ * ```
+ *
+ * @param message Optional message describing the reason for the abort. It will be included in the failure error.
+ */
+ abort(message?: string): never;
+
/**
* Marks a test as "slow". Slow test will be given triple the default timeout.
*
diff --git a/tests/playwright-test/test-modifiers.spec.ts b/tests/playwright-test/test-modifiers.spec.ts
index 8e985bd069..abe3f1682c 100644
--- a/tests/playwright-test/test-modifiers.spec.ts
+++ b/tests/playwright-test/test-modifiers.spec.ts
@@ -757,6 +757,42 @@ test('should skip beforeEach hooks upon modifiers', async ({ runInlineTest }) =>
expect(result.skipped).toBe(1);
});
+test('test.abort should fail the test immediately', async ({ runInlineTest }) => {
+ const result = await runInlineTest({
+ 'a.test.ts': `
+ import { test, expect } from '@playwright/test';
+ test('aborted', async () => {
+ test.abort('boom');
+ // Should not be reached.
+ expect(1).toBe(2);
+ });
+ `,
+ });
+ expect(result.exitCode).toBe(1);
+ expect(result.failed).toBe(1);
+ expect(result.output).toContain('Test aborted: boom');
+});
+
+test('test.abort from a fixture should fail the test', async ({ runInlineTest }) => {
+ const result = await runInlineTest({
+ 'a.test.ts': `
+ import { test as base, expect } from '@playwright/test';
+ const test = base.extend({
+ guarded: async ({}, use) => {
+ test.abort('not allowed');
+ await use(1);
+ },
+ });
+ test('aborted from fixture', async ({ guarded }) => {
+ expect(guarded).toBe(1);
+ });
+ `,
+ });
+ expect(result.exitCode).toBe(1);
+ expect(result.failed).toBe(1);
+ expect(result.output).toContain('Test aborted: not allowed');
+});
+
test('test.slow should be idempotent', async ({ runInlineTest }) => {
const result = await runInlineTest({
'a.test.ts': `
diff --git a/utils/generate_types/overrides-test.d.ts b/utils/generate_types/overrides-test.d.ts
index 02df783768..d92b3ee455 100644
--- a/utils/generate_types/overrides-test.d.ts
+++ b/utils/generate_types/overrides-test.d.ts
@@ -173,6 +173,8 @@ export interface TestType<TestArgs extends {}, WorkerArgs extends {}> {
only(title: string, details: TestDetails, body: TestBody<TestArgs & WorkerArgs>): void;
}
+ abort(message?: string): never;
+
slow(): void;
slow(condition: boolean, description?: string): void;
slow(callback: ConditionBody<TestArgs & WorkerArgs>, description?: string): void;