docs: better expect.extend docs (#27515)

docs/src/test-configuration-js.md

@@ -176,12 +176,14 @@ export const expect = baseExpect.extend({
     }
 
     const message = pass
-      ? () => this.utils.matcherHint('toHaveAmount', locator, expected, { isNot: this.isNot }) +
+      ? () => this.utils.matcherHint('toHaveAmount', undefined, undefined, { isNot: this.isNot }) +
           '\n\n' +
+          `Locator: \${locator}\n`,
           `Expected: \${this.isNot ? 'not' : ''}\${this.utils.printExpected(expected)}\n` +
           (matcherResult ? `Received: ${this.utils.printReceived(matcherResult.actual)}` : '')
-      : () =>  this.utils.matcherHint('toHaveAmount', locator, expected, expectOptions) +
+      : () =>  this.utils.matcherHint('toHaveAmount', undefined, undefined, expectOptions) +
           '\n\n' +
+          `Locator: \${locator}\n`,
           `Expected: ${this.utils.printExpected(expected)}\n` +
           (matcherResult ? `Received: ${this.utils.printReceived(matcherResult.actual)}` : '');
 
@@ -209,3 +211,24 @@ test('amount', async () => {
 :::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`.
 :::
+
+### Combine custom matchers from multiple modules
+
+You can combine custom matchers from multiple files or modules.
+
+```js title="fixtures.ts"
+import { composedTest, composedExpect } from '@playwright/test';
+import { test as dbTest, expect as dbExpect } from 'database-test-utils';
+import { test as a11yTest, expect as a11yExpect } from 'a11y-test-utils';
+
+export const expect = composedExpect(dbExpect, a11yExpect);
+export const test = composedTest(dbTest, a11yTest);
+```
+
+```js title="test.spec.ts"
+import { test, expect } from './fixtures';
+
+test('passes', async ({ database }) => {
+  await expect(database).toHaveDatabaseUser('admin');
+});
+```