From 4621f61c7d9a995e4d029ec2d84801761d3e0e6f Mon Sep 17 00:00:00 2001
From: Yury Semikhatsky <yurys@chromium.org>
Date: Thu, 9 Dec 2021 15:21:04 -0800
Subject: [PATCH] docs: converting Locator to FrameLocator (#10839)

---
 docs/src/api/class-framelocator.md        | 23 +++++++++++++++++++++++
 packages/playwright-core/types/types.d.ts |  9 +++++++++
 2 files changed, 32 insertions(+)

diff --git a/docs/src/api/class-framelocator.md b/docs/src/api/class-framelocator.md
index d05555d442..bb2ad7da0b 100644
--- a/docs/src/api/class-framelocator.md
+++ b/docs/src/api/class-framelocator.md
@@ -71,6 +71,29 @@ await page.FrameLocator(".result-frame").Locator("button").ClickAsync();
 await page.FrameLocator(".result-frame").First.Locator("button").ClickAsync();
 ```
 
+**Converting Locator to FrameLocator**
+
+If you have a [Locator] object pointing to an `iframe` it can be converted to [FrameLocator] using [`:scope`](https://developer.mozilla.org/en-US/docs/Web/CSS/:scope) CSS selector:
+
+```js
+const frameLocator = locator.frameLocator(':scope');
+```
+
+```java
+Locator frameLocator = locator.frameLocator(':scope');
+```
+
+```python async
+frameLocator = locator.frame_locator(":scope");
+```
+
+```python sync
+frameLocator = locator.frame_locator(":scope");
+```
+
+```csharp
+var frameLocator = locator.FrameLocator(":scope");
+```
 
 ## method: FrameLocator.first
 - returns: <[FrameLocator]>
diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts
index d98b8ddbc5..724bda1334 100644
--- a/packages/playwright-core/types/types.d.ts
+++ b/packages/playwright-core/types/types.d.ts
@@ -13608,6 +13608,15 @@ export interface FileChooser {
  * await page.frameLocator('.result-frame').first().locator('button').click();
  * ```
  *
+ * **Converting Locator to FrameLocator**
+ *
+ * If you have a [Locator] object pointing to an `iframe` it can be converted to [FrameLocator] using
+ * [`:scope`](https://developer.mozilla.org/en-US/docs/Web/CSS/:scope) CSS selector:
+ *
+ * ```js
+ * const frameLocator = locator.frameLocator(':scope');
+ * ```
+ *
  */
 export interface FrameLocator {
   /**