From 4a52bc9465ecdca35ee59a088e7700ceaf02299f Mon Sep 17 00:00:00 2001
From: Dmitry Gozman <dgozman@gmail.com>
Date: Tue, 1 Feb 2022 14:34:47 -0800
Subject: [PATCH] docs: add option fixtures section to release notes (#11794)

---
 docs/src/release-notes-js.md     | 47 ++++++++++++++++++++++++++++++--
 docs/src/test-fixtures-js.md     |  4 +++
 docs/src/test-parameterize-js.md |  4 +++
 3 files changed, 52 insertions(+), 3 deletions(-)

diff --git a/docs/src/release-notes-js.md b/docs/src/release-notes-js.md
index 4fc4ecf5df..19177aaebb 100644
--- a/docs/src/release-notes-js.md
+++ b/docs/src/release-notes-js.md
@@ -50,9 +50,50 @@ This will create a Playwright Test configuration file, optionally add examples,
 ### New APIs & changes
 
 - new [`testCase.repeatEachIndex`](./api/class-testcase#test-case-repeat-each-index) API
-- new [option fixtures](./test-fixtures#fixtures-options)
 - [`acceptDownloads`](./api/class-browser#browser-new-context-option-accept-downloads) option now defaults to `true`
 
+### Breaking change: custom config options
+
+Custom config options are a convenient way to parametrize projects with different values. Learn more in [this guide](./test-parameterize#parameterized-projects).
+
+Previously, any fixture introduced through [`method: Test.extend`] could be overridden in the [`property: TestProject.use`] config section. For example,
+
+```js
+// WRONG: THIS SNIPPET DOES NOT WORK SINCE v1.18.
+
+// fixtures.js
+const test = base.extend({
+  myParameter: 'default',
+});
+
+// playwright.config.js
+module.exports = {
+  use: {
+    myParameter: 'value',
+  },
+};
+```
+
+The proper way to make a fixture parametrized in the config file is to specify `option: true` when defining the fixture. For example,
+
+```js
+// CORRECT: THIS SNIPPET WORKS SINCE v1.18.
+
+// fixtures.js
+const test = base.extend({
+  // Fixtures marked as "option: true" will get a value specified in the config,
+  // or fallback to the default value.
+  myParameter: ['default', { option: true }],
+});
+
+// playwright.config.js
+module.exports = {
+  use: {
+    myParameter: 'value',
+  },
+};
+```
+
 ### Browser Versions
 
 - Chromium 99.0.4812.0
@@ -447,8 +488,8 @@ import { PlaywrightTestConfig } from '@playwright/test';
 const config: PlaywrightTestConfig = {
   webServer: {
     command: 'npm run start', // command to launch
-    port: 3000, // port to await for 
-    timeout: 120 * 1000, 
+    port: 3000, // port to await for
+    timeout: 120 * 1000,
     reuseExistingServer: !process.env.CI,
   },
 };
diff --git a/docs/src/test-fixtures-js.md b/docs/src/test-fixtures-js.md
index e0b49da3d5..ab401fd49f 100644
--- a/docs/src/test-fixtures-js.md
+++ b/docs/src/test-fixtures-js.md
@@ -468,6 +468,10 @@ export { expect } from '@playwright/test';
 
 ## Fixtures-options
 
+:::note
+Overriding custom fixtures in the config file has changed in version 1.18. [Learn more](./release-notes#breaking-change-custom-config-options).
+:::
+
 Playwright Test supports running multiple test projects that can be separately configured. You can use "option" fixtures to make your configuration options declarative and type-checked. Learn more about [parametrizing tests](./test-parameterize.md).
 
 Below we'll create a `defaultItem` option in addition to the `todoPage` fixture from other examples. This option will be set in configuration file. Note the tuple syntax and `{ option: true }` argument.
diff --git a/docs/src/test-parameterize-js.md b/docs/src/test-parameterize-js.md
index c2fc16fd8c..f356ff08d5 100644
--- a/docs/src/test-parameterize-js.md
+++ b/docs/src/test-parameterize-js.md
@@ -177,3 +177,7 @@ export const test = base.test.extend<TestOptions>({
   },
 });
 ```
+
+:::note
+Parametrized projects behavior has changed in version 1.18. [Learn more](./release-notes#breaking-change-custom-config-options).
+:::