From 57fcc642831820910e92b9889d0578fd51adc25e Mon Sep 17 00:00:00 2001
From: Andrey Lushnikov <aslushnikov@gmail.com>
Date: Thu, 25 Feb 2021 10:42:52 -0800
Subject: [PATCH] docs: more clarity in the attribute selectors (#5621)

Fixes #5615
---
 docs/src/selectors.md | 37 ++++++++++++++++++++++++++++++++++++-
 1 file changed, 36 insertions(+), 1 deletion(-)

diff --git a/docs/src/selectors.md b/docs/src/selectors.md
index 534d3404a0ca96..fcb392e9dcf052 100644
--- a/docs/src/selectors.md
+++ b/docs/src/selectors.md
@@ -449,7 +449,42 @@ converts `'//html/body'` to `'xpath=//html/body'`.
 
 ## id, data-testid, data-test-id, data-test selectors
 
-Attribute engines are selecting based on the corresponding attribute value. For example: `data-test-id=foo` is equivalent to `css=[data-test-id="foo"]`, and `id:light=foo` is equivalent to `css:light=[id="foo"]`.
+Playwright supports a shorthand for selecting elements using certain elements. Currently, only
+the following attributes are supported:
+
+- `id`
+- `data-testid`
+- `data-test-id`
+- `data-test`
+
+```js
+// Fill an input with the id "username"
+await page.fill('id=username', 'value');
+
+// Click an element with data-test-id "submit"
+await page.click('data-test-id=submit');
+```
+
+```python async
+# Fill an input with the id "username"
+await page.fill('id=username', 'value')
+
+# Click an element with data-test-id "submit"
+await page.click('data-test-id=submit')
+```
+
+```python sync
+# Fill an input with the id "username"
+page.fill('id=username', 'value')
+
+# Click an element with data-test-id "submit"
+page.click('data-test-id=submit')
+```
+
+:::note
+Attribute selectors piece shadow DOM. To opt-out from this behavior, use `:light` suffix after attribute, for example `page.click('data-test-id:light=submit')
+:::
+
 
 ## Pick n-th match from the query result