From 0a686fbf249330051211e1367a932652fb0cb1df Mon Sep 17 00:00:00 2001
From: Nikolay Vitkov <34244704+Lightning00Blade@users.noreply.github.com>
Date: Wed, 16 Aug 2023 18:58:32 +0200
Subject: [PATCH] docs(ng-schematics): add Protractor migration info (#10741)

---
 docs/ng-schematics.md            | 45 ++++++++++++++++++++++++++++++++
 packages/ng-schematics/README.md | 45 ++++++++++++++++++++++++++++++++
 2 files changed, 90 insertions(+)

diff --git a/docs/ng-schematics.md b/docs/ng-schematics.md
index bb6853a6..da31c37d 100644
--- a/docs/ng-schematics.md
+++ b/docs/ng-schematics.md
@@ -111,3 +111,48 @@ The schematics utilize `@angular-devkit/schematics/testing` for verifying correc
 ```bash
 npm run test
 ```
+
+## Migrating from Protractor
+
+### Browser
+
+Puppeteer has its own [`browser`](https://pptr.dev/api/puppeteer.browser) that exposes different API compared to the one exposed by Protractor.
+
+```ts
+import puppeteer from 'puppeteer';
+
+(async () => {
+  const browser = await puppeteer.launch();
+
+  it('should work', () => {
+    const page = await browser.newPage();
+
+    // Query elements
+    const element = await page.$('my-component');
+
+    // Do actions
+    await element.click();
+  });
+
+  await browser.close();
+})();
+```
+
+### Query Selectors
+
+Puppeteer supports multiple types of selectors, namely, the CSS, ARIA, text, XPath and pierce selectors.
+The following table shows Puppeteer's equivalents to [Protractor By](https://www.protractortest.org/#/api?view=ProtractorBy).
+
+> For improved reliability and reduced flakiness try our
+> **Experimental** [Locators API](https://pptr.dev/guides/locators)
+
+| By                | Protractor code                                                   | Puppeteer querySelector                                      |
+| ----------------- | ----------------------------------------------------------------- | ------------------------------------------------------------ |
+| CSS               | Single: `$(by.css('<CSS>'))` <br> Multiple: `$$(by.css('<CSS>'))` | Single: `page.$('<CSS>')` <br> Multiple: `page.$$('<CSS>')`  |
+| Id                | `$(by.id('<ID>'))`                                                | `page.$('#<ID>')`                                            |
+| CssContainingText | `$(by.cssContainingText('<CSS>', '<TEXT>'))`                      | `page.$('<CSS> ::-p-text(<TEXT>)')` `                        |
+| DeepCss           | `$(by.deepCss('<CSS>'))`                                          | `page.$(':scope >>> <CSS>')`                                 |
+| XPath             | `$(by.xpath('<XPATH>'))`                                          | `page.$('::-p-xpath(<XPATH>)')`                              |
+| JS                | `$(by.js('document.querySelector("<CSS>")'))`                     | `page.evaluateHandle(() => document.querySelector('<CSS>'))` |
+
+> For advanced use cases such as Protractor's `by.addLocator` you can check Puppeteer's [Custom selectors](https://pptr.dev/guides/query-selectors#custom-selectors).
diff --git a/packages/ng-schematics/README.md b/packages/ng-schematics/README.md
index bb6853a6..da31c37d 100644
--- a/packages/ng-schematics/README.md
+++ b/packages/ng-schematics/README.md
@@ -111,3 +111,48 @@ The schematics utilize `@angular-devkit/schematics/testing` for verifying correc
 ```bash
 npm run test
 ```
+
+## Migrating from Protractor
+
+### Browser
+
+Puppeteer has its own [`browser`](https://pptr.dev/api/puppeteer.browser) that exposes different API compared to the one exposed by Protractor.
+
+```ts
+import puppeteer from 'puppeteer';
+
+(async () => {
+  const browser = await puppeteer.launch();
+
+  it('should work', () => {
+    const page = await browser.newPage();
+
+    // Query elements
+    const element = await page.$('my-component');
+
+    // Do actions
+    await element.click();
+  });
+
+  await browser.close();
+})();
+```
+
+### Query Selectors
+
+Puppeteer supports multiple types of selectors, namely, the CSS, ARIA, text, XPath and pierce selectors.
+The following table shows Puppeteer's equivalents to [Protractor By](https://www.protractortest.org/#/api?view=ProtractorBy).
+
+> For improved reliability and reduced flakiness try our
+> **Experimental** [Locators API](https://pptr.dev/guides/locators)
+
+| By                | Protractor code                                                   | Puppeteer querySelector                                      |
+| ----------------- | ----------------------------------------------------------------- | ------------------------------------------------------------ |
+| CSS               | Single: `$(by.css('<CSS>'))` <br> Multiple: `$$(by.css('<CSS>'))` | Single: `page.$('<CSS>')` <br> Multiple: `page.$$('<CSS>')`  |
+| Id                | `$(by.id('<ID>'))`                                                | `page.$('#<ID>')`                                            |
+| CssContainingText | `$(by.cssContainingText('<CSS>', '<TEXT>'))`                      | `page.$('<CSS> ::-p-text(<TEXT>)')` `                        |
+| DeepCss           | `$(by.deepCss('<CSS>'))`                                          | `page.$(':scope >>> <CSS>')`                                 |
+| XPath             | `$(by.xpath('<XPATH>'))`                                          | `page.$('::-p-xpath(<XPATH>)')`                              |
+| JS                | `$(by.js('document.querySelector("<CSS>")'))`                     | `page.evaluateHandle(() => document.querySelector('<CSS>'))` |
+
+> For advanced use cases such as Protractor's `by.addLocator` you can check Puppeteer's [Custom selectors](https://pptr.dev/guides/query-selectors#custom-selectors).