From 33a05446d27d62c700cf27a9108148c5f695ebbd Mon Sep 17 00:00:00 2001 From: Dmitry Gozman Date: Mon, 6 Feb 2023 14:51:24 -0800 Subject: [PATCH] fix(expect): update docs to point to GenericAssertions instead of expect library (#20688) Closes #20432. --- docs/src/test-advanced-js.md | 9 +++++++-- docs/src/test-api/class-test.md | 2 +- docs/src/test-assertions-js.md | 6 +++--- docs/src/writing-tests-js.md | 15 +++++++++------ packages/playwright-test/types/test.d.ts | 3 +-- 5 files changed, 21 insertions(+), 14 deletions(-) diff --git a/docs/src/test-advanced-js.md b/docs/src/test-advanced-js.md index a5074bd285..b5abfc2b56 100644 --- a/docs/src/test-advanced-js.md +++ b/docs/src/test-advanced-js.md @@ -599,9 +599,10 @@ export const test = base.extend<{}, { server: http.Server }>({ ## Add custom matchers using expect.extend -Playwright Test uses [`expect` library](https://jestjs.io/docs/expect) under the hood which has the functionality to extend it with [custom matchers](https://jestjs.io/docs/expect#expectextendmatchers). +You can extend Playwright assertions by providing custom matchers. These matchers will be available on the `expect` object. + +In this example we add a custom `toBeWithinRange` function in the configuration file. Custom matcher should return a `message` callback and a `pass` flag indicating whether the assertion passed. -In this example we add a custom `toBeWithinRange` function in the configuration file. ```js tab=js-js // playwright.config.js const { expect } = require('@playwright/test'); @@ -672,6 +673,10 @@ test('numeric ranges', () => { }); ``` +:::note +Do not confuse Playwright's `expect` with the [`expect` library](https://jestjs.io/docs/expect). The latter is not fully integrated with Playwright test runner, so make sure to use Playwright's own `expect`. +::: + For TypeScript, also add the following to your [`global.d.ts`](https://www.typescriptlang.org/docs/handbook/declaration-files/templates/global-d-ts.html). If it does not exist, you need to create it inside your repository. Make sure that your `global.d.ts` gets included inside your `tsconfig.json` via the `include` or `compilerOptions.typeRoots` option so that your IDE will pick it up. You don't need it for JavaScript. diff --git a/docs/src/test-api/class-test.md b/docs/src/test-api/class-test.md index 7bc8f3b2e1..6099fc4b63 100644 --- a/docs/src/test-api/class-test.md +++ b/docs/src/test-api/class-test.md @@ -2,7 +2,7 @@ * since: v1.10 * langs: js -Playwright Test provides a `test` function to declare tests and [`expect` function](https://jestjs.io/docs/expect) to write assertions. +Playwright Test provides a `test` function to declare tests and `expect` function to write assertions. ```js tab=js-js const { test, expect } = require('@playwright/test'); diff --git a/docs/src/test-assertions-js.md b/docs/src/test-assertions-js.md index 318ce106df..4d6a867f27 100644 --- a/docs/src/test-assertions-js.md +++ b/docs/src/test-assertions-js.md @@ -3,20 +3,20 @@ id: test-assertions title: "Assertions" --- -Playwright Test uses [expect](https://jestjs.io/docs/expect) library for test assertions. This library provides a lot of matchers like `toEqual`, `toContain`, `toMatch`, `toMatchSnapshot` and many more: +Playwright includes test assertions in the form of `expect` function. To make an assertion, call `expect(value)` and choose a matcher that reflects the expectation. There are many [generic matchers](./api/class-genericassertions.md) like `toEqual`, `toContain`, `toBeTruthy` that can be used to assert any conditions. ```js expect(success).toBeTruthy(); ``` -Playwright also extends it with convenience async matchers that will wait until +Playwright also includes web-specific [async matchers](./api/class-locatorassertions.md) that will wait until the expected condition is met. Consider the following example: ```js await expect(page.getByTestId('status')).toHaveText('Submitted'); ``` -Playwright Test will be re-testing the element with the test id of `status` until the fetched element has the `"Submitted"` text. It will re-fetch the element and check it over and over, until the condition is met or until the timeout is reached. You can either pass this timeout or configure it once via the [`property: TestConfig.expect`] value in the test config. +Playwright will be re-testing the element with the test id of `status` until the fetched element has the `"Submitted"` text. It will re-fetch the element and check it over and over, until the condition is met or until the timeout is reached. You can either pass this timeout or configure it once via the [`property: TestConfig.expect`] value in the test config. By default, the timeout for assertions is set to 5 seconds. Learn more about [various timeouts](./test-timeouts.md). diff --git a/docs/src/writing-tests-js.md b/docs/src/writing-tests-js.md index 4f6e65aff8..aac3067fe6 100644 --- a/docs/src/writing-tests-js.md +++ b/docs/src/writing-tests-js.md @@ -115,12 +115,15 @@ learn more about them. ## Assertions -Playwright Test uses the [expect](https://jestjs.io/docs/expect) library for -[test assertions](./test-assertions.md) which provides matchers like -`toEqual`, `toContain`, `toMatch`, `toBe` and many more. It also extends -this library with the convenience async matchers that will wait until the expected condition is met. -Using these matchers allows making the tests non-flaky and resilient. For example, this code will wait until -the page gets the title containing "Playwright": +Playwright includes [test assertions](./test-assertions.md) in the form of `expect` function. To make an assertion, call `expect(value)` and choose a matcher that reflects the expectation. + +There are many generic matchers like `toEqual`, `toContain`, `toBeTruthy` that can be used to assert any conditions. + +```js +expect(success).toBeTruthy(); +``` + +Playwright also includes async matchers that will wait until the expected condition is met. Using these matchers allows making the tests non-flaky and resilient. For example, this code will wait until the page gets the title containing "Playwright": ```js await expect(page).toHaveTitle(/Playwright/); diff --git a/packages/playwright-test/types/test.d.ts b/packages/playwright-test/types/test.d.ts index 9ba86ad4fc..1cc94157ab 100644 --- a/packages/playwright-test/types/test.d.ts +++ b/packages/playwright-test/types/test.d.ts @@ -2317,8 +2317,7 @@ interface TestFunction { } /** - * Playwright Test provides a `test` function to declare tests and [`expect` function](https://jestjs.io/docs/expect) - * to write assertions. + * Playwright Test provides a `test` function to declare tests and `expect` function to write assertions. * * ```js * import { test, expect } from '@playwright/test';