playwright-decorators/dist/index.d.ts

Decorators for writing Playwright based tests.

import { PlaywrightTestArgs, PlaywrightTestOptions, PlaywrightWorkerArgs, PlaywrightWorkerOptions, TestInfo as PlaywrightTestInfo, TestType as PlaywrightTestType } from '@playwright/test';

export type TestInfo = PlaywrightTestInfo;
export type TestArgs<T = void> = T & PlaywrightTestArgs & PlaywrightTestOptions & PlaywrightWorkerArgs & PlaywrightWorkerOptions;
type TestMethod<T = void> = (args: TestArgs<T>, testInfo: TestInfo) => void | Promise<void>;
type TestClass = {
	new (...args: any[]): any;
};
type TestType<T = any> = PlaywrightTestType<TestArgs<T>, PlaywrightWorkerArgs & PlaywrightWorkerOptions>;
type SuiteHook = () => void;
interface SuiteDecoratorOptions {
	/**
	 * Name of the suite. Default: name of the suite class
	 */
	name?: string;
	/**
	 * Declares a focused suite.
	 * If there are some focused @test(s) or @suite(s), all of them will be run but nothing else.
	 */
	only?: boolean;
}
declare class SuiteDecorator implements SuiteDecoratorOptions {
	private suiteClass;
	name: string;
	only: boolean;
	private initializedHooks;
	constructor(suiteClass: TestClass, options: SuiteDecoratorOptions);
	private handleInitializedHooks;
	private runSuite;
	/**
	 * Run playwright.describe function using all collected data.
	 */
	run(): void;
	/**
	 * Declares an `initialized` hook that is executed in `playwright.describe` context, when suite is executed.
	 * It is equivalent to code: playwright.describe(..., () => { initialized(); ... })
	 */
	initialized(hookFn: SuiteHook): void;
}
/**
 * Mark class as test suite.
 * Decorator creates a `describe` block and runs all methods decorated by `@test` inside it.
 *
 * Behaviour of decorator can be modified by other decorators using injected `suiteDecorator` property.
 */
export declare const suite: (options?: SuiteDecoratorOptions) => <T extends TestClass>(constructor: T, context: ClassDecoratorContext) => void;
type TestHook = () => void | Promise<void>;
interface TestDecoratorOptions {
	/**
	 * Name of the test. Default: name of the method
	 */
	name?: string;
	/**
	 * Declares a focused test.
	 * If there are some focused @test(s) or @suite(s), all of them will be run but nothing else.
	 */
	only?: boolean;
	/**
	 * Custom playwright instance to use instead of standard one.
	 * For example, provide result of `playwright.extend<T>(customFixture)` to ensure availability of custom fixture in the `test` method.
	 */
	playwright?: TestType;
}
declare class TestDecorator implements TestDecoratorOptions {
	private testMethod;
	name: string;
	only: boolean;
	playwright: import("@playwright/test").TestType<import("@playwright/test").PlaywrightTestArgs & import("@playwright/test").PlaywrightTestOptions, import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions>;
	private beforeTestHooks;
	private afterTestHooks;
	constructor(testMethod: any, options: TestDecoratorOptions);
	private handleBeforeTestHooks;
	private handleAfterTestHooks;
	/**
	 * Run playwright.test function using all collected data.
	 */
	run(executionContext: ClassMethodDecoratorContext): void;
	/**
	 * Declares an `before` hook that is executed in `playwright()` context just before execution of test code.
	 * It is equivalent to code: playwright(..., () => { beforeTest(); ... })
	 */
	beforeTest(initializer: TestHook): void;
	/**
	 * Declares an `after` hook that is executed in `playwright()` context just after execution of test code.
	 * It is equivalent to code: playwright(..., () => { ...; afterTest() })
	 */
	afterTest(initializer: TestHook): void;
}
/**
 * Mark method as test.
 * Decorator creates a `test` block and runs method inside it.
 * Target class should be marked by @suite decorator.
 *
 * Behaviour of decorator can be modified by other decorators using injected `testDecorator` property.
 */
export declare const test: <T = void>(options?: TestDecoratorOptions) => (originalMethod: TestMethod<T>, context: ClassMethodDecoratorContext) => void;
interface BeforeAllDecoratorOptions<T> {
	/**
	 * Custom playwright instance to use instead of standard one.
	 * For example, provide result of `playwright.extend<T>(customFixture)` to ensure availability of custom fixture in the `beforeAll` hook.
	 */
	playwright?: TestType<T>;
}
/**
 * Run method before all tests in the suite.
 * Target class should be marked by @suite decorator.
 */
export declare const beforeAll: <T = void>(options?: BeforeAllDecoratorOptions<T> | undefined) => (originalMethod: TestMethod<T>, context: ClassMethodDecoratorContext) => void;
interface BeforeEachDecoratorOptions<T> {
	/**
	 * Custom playwright instance to use instead of standard one.
	 * For example, provide result of `playwright.extend<T>(customFixture)` to ensure availability of custom fixture in the `beforeEach` hook.
	 */
	playwright?: TestType<T>;
}
/**
 * Run method before each test in the suite.
 * Target class should be marked by @suite decorator.
 */
export declare const beforeEach: <T = void>(options?: BeforeEachDecoratorOptions<T> | undefined) => (originalMethod: TestMethod<T>, context: ClassMethodDecoratorContext) => void;
interface AfterAllDecoratorOptions<T> {
	/**
	 * Custom playwright instance to use instead of standard one.
	 * For example, provide result of `playwright.extend<T>(customFixture)` to ensure availability of custom fixture in the `afterAll` hook.
	 */
	playwright?: TestType<T>;
}
/**
 * Run method after all tests in the suite.
 * Target class should be marked by @suite decorator.
 */
export declare const afterAll: <T = void>(options?: AfterAllDecoratorOptions<T> | undefined) => (originalMethod: TestMethod<T>, context: ClassMethodDecoratorContext) => void;
interface AfterEachDecoratorOptions<T> {
	/**
	 * Custom playwright instance to use instead of standard one.
	 * For example, provide result of `playwright.extend<T>(customFixture)` to ensure availability of custom fixture in the `afterEach` hook.
	 */
	playwright?: TestType<T>;
}
/**
 * Run method after each test in suite.
 * Target class should be marked by @suite decorator.
 */
export declare const afterEach: <T = void>(options?: AfterEachDecoratorOptions<T> | undefined) => (originalMethod: TestMethod<T>, context: ClassMethodDecoratorContext) => void;
/**
 * Skip @test or @suite (with optional reason).
 */
export declare const skip: (reason?: string) => (originalMethod: TestClass | TestMethod, context: ClassDecoratorContext<abstract new (...args: any) => any> | ClassMethodDecoratorContext<unknown, (this: unknown, ...args: any) => any>) => void;
/**
 * Marks a @test or @suite as "slow" (with optional reason).
 * Slow test will be given triple the default timeout.
 */
export declare const slow: (reason?: string) => (originalMethod: TestClass | TestMethod, context: ClassDecoratorContext<abstract new (...args: any) => any> | ClassMethodDecoratorContext<unknown, (this: unknown, ...args: any) => any>) => void;
/**
 * Marks a @test or @suite as "should fail".
 * Playwright Test runs this test and ensures that it is actually failing.
 * This is useful for documentation purposes to acknowledge that some functionality is broken until it is fixed.
 */
export declare const fail: (reason?: string) => (originalMethod: TestClass | TestMethod, context: ClassDecoratorContext<abstract new (...args: any) => any> | ClassMethodDecoratorContext<unknown, (this: unknown, ...args: any) => any>) => void;
/**
 * Marks a @test or @suite as "fixme", with the intention to fix (with optional reason).
 * Decorated tests or suites will not be run.
 */
export declare const fixme: (reason?: string) => (originalMethod: TestClass | TestMethod, context: ClassDecoratorContext<abstract new (...args: any) => any> | ClassMethodDecoratorContext<unknown, (this: unknown, ...args: any) => any>) => void;
/**
 * Declares a focused test.
 * If there are some focused @test(s) or @suite(s), all of them will be run but nothing else.
 */
export declare const only: () => (originalMethod: TestClass | TestMethod, context: ClassDecoratorContext<abstract new (...args: any) => any> | ClassMethodDecoratorContext<unknown, (this: unknown, ...args: any) => any>) => void;
interface AnnotationDecoratorOptions {
	type: "skip" | "fail" | "issue" | "slow" | string;
	description?: string;
}
/**
 * Add custom annotation to a @test.
 * Annotations are accessible via test.info().annotations. Many reporters show annotations, for example 'html'.
 */
export declare const annotation: (options: AnnotationDecoratorOptions) => (testMethod: TestMethod, context: ClassMethodDecoratorContext<unknown, (this: unknown, ...args: any) => any>) => void;
/**
 * Adds tags to `@test` or `@suite`.
 * You can later run test(s) or suite(s) with specific tag, using `npx playwright test --grep "@nameOfTag"` command.
 * For example: to run tests/suites with `x` tag, please run `npx playwright test --grep "@x"`
 */
export declare const tag: (tags: string[]) => (originalMethod: TestClass | TestMethod, context: ClassDecoratorContext<abstract new (...args: any) => any> | ClassMethodDecoratorContext<unknown, (this: unknown, ...args: any) => any>) => void;
/**
 * Set the maximum number of retry attempts given to failed @tests in the @suite
 * @param retries the number of retries for each @test.
 */
export declare const retries: (retries: number) => (suiteClass: TestClass, context: ClassDecoratorContext<abstract new (...args: any) => any>) => void;
/**
 * Runs a @test or @suite in debug mode.
 * Tests or suites without the @debug decorator will not be excluded.
 * Learn more about debug mode: https://playwright.dev/docs/debug
 */
export declare const debug: () => (originalMethod: TestClass | TestMethod, context: ClassDecoratorContext<abstract new (...args: any) => any> | ClassMethodDecoratorContext<unknown, (this: unknown, ...args: any) => any>) => void;
/**
 * Runs a @test(s) or @suite(s) in preview (headed browser) mode, simulating user interaction (slowing down each operation by 1000ms).
 * Tests or suites without the @preview decorator will not be excluded.
 */
export declare const preview: () => (originalMethod: TestClass | TestMethod, context: ClassDecoratorContext<abstract new (...args: any) => any> | ClassMethodDecoratorContext<unknown, (this: unknown, ...args: any) => any>) => void;
/**
 * Generates afterAll, afterEach, test, beforeAll, beforeEach decorators with access to custom fixture.
 * @param customPlaywright - method returned from playwright.extend<T>
 */
export declare const extend: <T>(customPlaywright: TestType<T>) => {
	afterAll: (options?: AfterAllDecoratorOptions<unknown> | undefined) => (originalMethod: TestMethod<T>, context: ClassMethodDecoratorContext<unknown, (this: unknown, ...args: any) => any>) => void;
	afterEach: (options?: AfterEachDecoratorOptions<unknown> | undefined) => (originalMethod: TestMethod<T>, context: ClassMethodDecoratorContext<unknown, (this: unknown, ...args: any) => any>) => void;
	test: (options?: TestDecoratorOptions | undefined) => (originalMethod: TestMethod<T>, context: ClassMethodDecoratorContext<unknown, (this: unknown, ...args: any) => any>) => void;
	beforeAll: (options?: BeforeAllDecoratorOptions<unknown> | undefined) => (originalMethod: TestMethod<T>, context: ClassMethodDecoratorContext<unknown, (this: unknown, ...args: any) => any>) => void;
	beforeEach: (options?: BeforeEachDecoratorOptions<unknown> | undefined) => (originalMethod: TestMethod<T>, context: ClassMethodDecoratorContext<unknown, (this: unknown, ...args: any) => any>) => void;
};
type CustomSuiteDecorator = (params: {
	/**
	 * @suite decorator context
	 */
	suite: SuiteDecorator;
	/**
	 * The suite class that is being decorated.
	 */
	suiteClass: TestClass;
	/**
	 * The context of the suite class that is being decorated.
	 */
	context: ClassDecoratorContext;
}) => void;
/**
 * Generates a decorator specifically intended for use with the @suite.
 * Applying this decorator in other contexts will result in an error.
 * @param name name of the decorator
 * @param suiteDecorator a custom decorator function
 */
export declare const createSuiteDecorator: (name: string, suiteDecorator: CustomSuiteDecorator) => (suiteClass: TestClass, context: ClassDecoratorContext) => void;
type CustomTestDecorator = (params: {
	/**
	 * @test decorator context
	 */
	test: TestDecorator;
	/**
	 * The test method that is being decorated.
	 */
	testMethod: TestMethod;
	/**
	 * The context of the test method that is being decorated.
	 */
	context: ClassMethodDecoratorContext;
}) => void;
/**
 * Generates a decorator specifically intended for use with the @test.
 * Applying this decorator in other contexts will result in an error.
 * @param name name of the decorator
 * @param testDecorator a custom decorator function
 */
export declare const createTestDecorator: (name: string, testDecorator: CustomTestDecorator) => (testMethod: TestMethod, context: ClassMethodDecoratorContext) => void;
/**
 * Generates a decorator specifically intended for use with both @suite and @test.
 * @param name name of the decorator
 * @param suiteDecorator a custom decorator function intended for use with @suite
 * @param testDecorator a custom decorator function intended for use with @test
 */
export declare const createSuiteAndTestDecorator: (name: string, suiteDecorator: CustomSuiteDecorator, testDecorator: CustomTestDecorator) => (originalMethod: TestClass | TestMethod, context: ClassDecoratorContext | ClassMethodDecoratorContext) => void;

export {};