docs(testing): add caution for piercing shadow DOM

docs/testing/stencil-testrunner/05-e2e-testing.md

@@ -85,6 +85,18 @@ Use the "piercing" selector `>>>` to query for an object inside a component's sh
 const el = await page.find('foo-component >>> .close-button');
 ```
 
+:::caution
+Make sure to only use `>>>` once in your query. Puppeteer does not support nested deep selectors. Instead, separate the calls if possible into two queries, e.g.:
+
+```ts
+// 👎 multiple nested deep selector aren't supported
+const otherShadowElement = await page.find('my-component >>> div > my-other-component >>> h3');
+// 👍 separated calls using `>>>` once
+const divElement = await page.find('my-component >>> div');
+const otherShadowElement = await divElement.find('my-other-component >>> h3');
+```
+:::
+
 ### Set a @Prop() on a component
 
 Use `page.$eval` (part of the Puppeteer API) to set props or otherwise manipulate a component:

versioned_docs/version-v3/testing/e2e-testing.md

@@ -85,6 +85,18 @@ Use the "piercing" selector `>>>` to query for an object inside a component's sh
 const el = await page.find('foo-component >>> .close-button');
 ```
 
+:::caution
+Make sure to only use `>>>` once in your query. Puppeteer does not support nested deep selectors. Instead, separate the calls if possible into two queries, e.g.:
+
+```ts
+// 👎 multiple nested deep selector aren't supported
+const otherShadowElement = await page.find('my-component >>> div > my-other-component >>> h3');
+// 👍 separated calls using `>>>` once
+const divElement = await page.find('my-component >>> div');
+const otherShadowElement = await divElement.find('my-other-component >>> h3');
+```
+:::
+
 ### Set a @Prop() on a component
 
 Use `page.$eval` (part of the Puppeteer API) to set props or otherwise manipulate a component:

versioned_docs/version-v4.0/testing/e2e-testing.md

@@ -85,6 +85,18 @@ Use the "piercing" selector `>>>` to query for an object inside a component's sh
 const el = await page.find('foo-component >>> .close-button');
 ```
 
+:::caution
+Make sure to only use `>>>` once in your query. Puppeteer does not support nested deep selectors. Instead, separate the calls if possible into two queries, e.g.:
+
+```ts
+// 👎 multiple nested deep selector aren't supported
+const otherShadowElement = await page.find('my-component >>> div > my-other-component >>> h3');
+// 👍 separated calls using `>>>` once
+const divElement = await page.find('my-component >>> div');
+const otherShadowElement = await divElement.find('my-other-component >>> h3');
+```
+:::
+
 ### Set a @Prop() on a component
 
 Use `page.$eval` (part of the Puppeteer API) to set props or otherwise manipulate a component:

versioned_docs/version-v4.1/testing/e2e-testing.md

@@ -85,6 +85,18 @@ Use the "piercing" selector `>>>` to query for an object inside a component's sh
 const el = await page.find('foo-component >>> .close-button');
 ```
 
+:::caution
+Make sure to only use `>>>` once in your query. Puppeteer does not support nested deep selectors. Instead, separate the calls if possible into two queries, e.g.:
+
+```ts
+// 👎 multiple nested deep selector aren't supported
+const otherShadowElement = await page.find('my-component >>> div > my-other-component >>> h3');
+// 👍 separated calls using `>>>` once
+const divElement = await page.find('my-component >>> div');
+const otherShadowElement = await divElement.find('my-other-component >>> h3');
+```
+:::
+
 ### Set a @Prop() on a component
 
 Use `page.$eval` (part of the Puppeteer API) to set props or otherwise manipulate a component:

versioned_docs/version-v4.10/testing/e2e-testing.md

@@ -85,6 +85,18 @@ Use the "piercing" selector `>>>` to query for an object inside a component's sh
 const el = await page.find('foo-component >>> .close-button');
 ```
 
+:::caution
+Make sure to only use `>>>` once in your query. Puppeteer does not support nested deep selectors. Instead, separate the calls if possible into two queries, e.g.:
+
+```ts
+// 👎 multiple nested deep selector aren't supported
+const otherShadowElement = await page.find('my-component >>> div > my-other-component >>> h3');
+// 👍 separated calls using `>>>` once
+const divElement = await page.find('my-component >>> div');
+const otherShadowElement = await divElement.find('my-other-component >>> h3');
+```
+:::
+
 ### Set a @Prop() on a component
 
 Use `page.$eval` (part of the Puppeteer API) to set props or otherwise manipulate a component:

versioned_docs/version-v4.11/testing/e2e-testing.md

@@ -85,6 +85,18 @@ Use the "piercing" selector `>>>` to query for an object inside a component's sh
 const el = await page.find('foo-component >>> .close-button');
 ```
 
+:::caution
+Make sure to only use `>>>` once in your query. Puppeteer does not support nested deep selectors. Instead, separate the calls if possible into two queries, e.g.:
+
+```ts
+// 👎 multiple nested deep selector aren't supported
+const otherShadowElement = await page.find('my-component >>> div > my-other-component >>> h3');
+// 👍 separated calls using `>>>` once
+const divElement = await page.find('my-component >>> div');
+const otherShadowElement = await divElement.find('my-other-component >>> h3');
+```
+:::
+
 ### Set a @Prop() on a component
 
 Use `page.$eval` (part of the Puppeteer API) to set props or otherwise manipulate a component:

versioned_docs/version-v4.12/testing/e2e-testing.md

@@ -85,6 +85,18 @@ Use the "piercing" selector `>>>` to query for an object inside a component's sh
 const el = await page.find('foo-component >>> .close-button');
 ```
 
+:::caution
+Make sure to only use `>>>` once in your query. Puppeteer does not support nested deep selectors. Instead, separate the calls if possible into two queries, e.g.:
+
+```ts
+// 👎 multiple nested deep selector aren't supported
+const otherShadowElement = await page.find('my-component >>> div > my-other-component >>> h3');
+// 👍 separated calls using `>>>` once
+const divElement = await page.find('my-component >>> div');
+const otherShadowElement = await divElement.find('my-other-component >>> h3');
+```
+:::
+
 ### Set a @Prop() on a component
 
 Use `page.$eval` (part of the Puppeteer API) to set props or otherwise manipulate a component:

versioned_docs/version-v4.2/testing/e2e-testing.md

@@ -85,6 +85,18 @@ Use the "piercing" selector `>>>` to query for an object inside a component's sh
 const el = await page.find('foo-component >>> .close-button');
 ```
 
+:::caution
+Make sure to only use `>>>` once in your query. Puppeteer does not support nested deep selectors. Instead, separate the calls if possible into two queries, e.g.:
+
+```ts
+// 👎 multiple nested deep selector aren't supported
+const otherShadowElement = await page.find('my-component >>> div > my-other-component >>> h3');
+// 👍 separated calls using `>>>` once
+const divElement = await page.find('my-component >>> div');
+const otherShadowElement = await divElement.find('my-other-component >>> h3');
+```
+:::
+
 ### Set a @Prop() on a component
 
 Use `page.$eval` (part of the Puppeteer API) to set props or otherwise manipulate a component:

versioned_docs/version-v4.3/testing/e2e-testing.md

@@ -85,6 +85,18 @@ Use the "piercing" selector `>>>` to query for an object inside a component's sh
 const el = await page.find('foo-component >>> .close-button');
 ```
 
+:::caution
+Make sure to only use `>>>` once in your query. Puppeteer does not support nested deep selectors. Instead, separate the calls if possible into two queries, e.g.:
+
+```ts
+// 👎 multiple nested deep selector aren't supported
+const otherShadowElement = await page.find('my-component >>> div > my-other-component >>> h3');
+// 👍 separated calls using `>>>` once
+const divElement = await page.find('my-component >>> div');
+const otherShadowElement = await divElement.find('my-other-component >>> h3');
+```
+:::
+
 ### Set a @Prop() on a component
 
 Use `page.$eval` (part of the Puppeteer API) to set props or otherwise manipulate a component:

versioned_docs/version-v4.4/testing/e2e-testing.md

@@ -85,6 +85,18 @@ Use the "piercing" selector `>>>` to query for an object inside a component's sh
 const el = await page.find('foo-component >>> .close-button');
 ```
 
+:::caution
+Make sure to only use `>>>` once in your query. Puppeteer does not support nested deep selectors. Instead, separate the calls if possible into two queries, e.g.:
+
+```ts
+// 👎 multiple nested deep selector aren't supported
+const otherShadowElement = await page.find('my-component >>> div > my-other-component >>> h3');
+// 👍 separated calls using `>>>` once
+const divElement = await page.find('my-component >>> div');
+const otherShadowElement = await divElement.find('my-other-component >>> h3');
+```
+:::
+
 ### Set a @Prop() on a component
 
 Use `page.$eval` (part of the Puppeteer API) to set props or otherwise manipulate a component:

versioned_docs/version-v4.5/testing/e2e-testing.md

@@ -85,6 +85,18 @@ Use the "piercing" selector `>>>` to query for an object inside a component's sh
 const el = await page.find('foo-component >>> .close-button');
 ```
 
+:::caution
+Make sure to only use `>>>` once in your query. Puppeteer does not support nested deep selectors. Instead, separate the calls if possible into two queries, e.g.:
+
+```ts
+// 👎 multiple nested deep selector aren't supported
+const otherShadowElement = await page.find('my-component >>> div > my-other-component >>> h3');
+// 👍 separated calls using `>>>` once
+const divElement = await page.find('my-component >>> div');
+const otherShadowElement = await divElement.find('my-other-component >>> h3');
+```
+:::
+
 ### Set a @Prop() on a component
 
 Use `page.$eval` (part of the Puppeteer API) to set props or otherwise manipulate a component:

versioned_docs/version-v4.6/testing/e2e-testing.md

@@ -85,6 +85,18 @@ Use the "piercing" selector `>>>` to query for an object inside a component's sh
 const el = await page.find('foo-component >>> .close-button');
 ```
 
+:::caution
+Make sure to only use `>>>` once in your query. Puppeteer does not support nested deep selectors. Instead, separate the calls if possible into two queries, e.g.:
+
+```ts
+// 👎 multiple nested deep selector aren't supported
+const otherShadowElement = await page.find('my-component >>> div > my-other-component >>> h3');
+// 👍 separated calls using `>>>` once
+const divElement = await page.find('my-component >>> div');
+const otherShadowElement = await divElement.find('my-other-component >>> h3');
+```
+:::
+
 ### Set a @Prop() on a component
 
 Use `page.$eval` (part of the Puppeteer API) to set props or otherwise manipulate a component:

versioned_docs/version-v4.7/testing/e2e-testing.md

@@ -85,6 +85,18 @@ Use the "piercing" selector `>>>` to query for an object inside a component's sh
 const el = await page.find('foo-component >>> .close-button');
 ```
 
+:::caution
+Make sure to only use `>>>` once in your query. Puppeteer does not support nested deep selectors. Instead, separate the calls if possible into two queries, e.g.:
+
+```ts
+// 👎 multiple nested deep selector aren't supported
+const otherShadowElement = await page.find('my-component >>> div > my-other-component >>> h3');
+// 👍 separated calls using `>>>` once
+const divElement = await page.find('my-component >>> div');
+const otherShadowElement = await divElement.find('my-other-component >>> h3');
+```
+:::
+
 ### Set a @Prop() on a component
 
 Use `page.$eval` (part of the Puppeteer API) to set props or otherwise manipulate a component:

versioned_docs/version-v4.8/testing/e2e-testing.md

@@ -85,6 +85,18 @@ Use the "piercing" selector `>>>` to query for an object inside a component's sh
 const el = await page.find('foo-component >>> .close-button');
 ```
 
+:::caution
+Make sure to only use `>>>` once in your query. Puppeteer does not support nested deep selectors. Instead, separate the calls if possible into two queries, e.g.:
+
+```ts
+// 👎 multiple nested deep selector aren't supported
+const otherShadowElement = await page.find('my-component >>> div > my-other-component >>> h3');
+// 👍 separated calls using `>>>` once
+const divElement = await page.find('my-component >>> div');
+const otherShadowElement = await divElement.find('my-other-component >>> h3');
+```
+:::
+
 ### Set a @Prop() on a component
 
 Use `page.$eval` (part of the Puppeteer API) to set props or otherwise manipulate a component:

versioned_docs/version-v4.9/testing/e2e-testing.md

@@ -85,6 +85,18 @@ Use the "piercing" selector `>>>` to query for an object inside a component's sh
 const el = await page.find('foo-component >>> .close-button');
 ```
 
+:::caution
+Make sure to only use `>>>` once in your query. Puppeteer does not support nested deep selectors. Instead, separate the calls if possible into two queries, e.g.:
+
+```ts
+// 👎 multiple nested deep selector aren't supported
+const otherShadowElement = await page.find('my-component >>> div > my-other-component >>> h3');
+// 👍 separated calls using `>>>` once
+const divElement = await page.find('my-component >>> div');
+const otherShadowElement = await divElement.find('my-other-component >>> h3');
+```
+:::
+
 ### Set a @Prop() on a component
 
 Use `page.$eval` (part of the Puppeteer API) to set props or otherwise manipulate a component: