docs: add ng-schematics page (#10459)

docs/ng-schematics.md

@@ -0,0 +1,107 @@
+# Puppeteer Angular Schematic
+
+Adds Puppeteer-based e2e tests to your Angular project.
+
+## Getting started
+
+Run the command below in an Angular CLI app directory and follow the prompts.
+
+> Note this will add the schematic as a dependency to your project.
+
+```bash
+ng add @puppeteer/ng-schematics
+```
+
+Or you can use the same command followed by the [options](#options) below.
+
+Currently, this schematic supports the following test frameworks:
+
+- [**Jasmine**](https://jasmine.github.io/)
+- [**Jest**](https://jestjs.io/)
+- [**Mocha**](https://mochajs.org/)
+- [**Node Test Runner** _(Experimental)_](https://nodejs.org/api/test.html)
+
+With the schematics installed you can run E2E tests:
+
+```bash
+ng e2e
+```
+
+### Options
+
+When adding schematics to your project you can to provide following options:
+
+| Option               | Description                                                                                                             | Value                                      | Required |
+| -------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | -------- |
+| `--isDefaultTester`  | When true, replaces default `ng e2e` command.                                                                           | `boolean`                                  | `true`   |
+| `--exportConfig`     | When true, creates an empty [Puppeteer configuration](https://pptr.dev/guides/configuration) file. (`.puppeteerrc.cjs`) | `boolean`                                  | `true`   |
+| `--testingFramework` | The testing framework to install along side Puppeteer.                                                                  | `"jasmine"`, `"jest"`, `"mocha"`, `"node"` | `true`   |
+| `--port`             | The port to spawn server for E2E. If default is used `ng serve` and `ng e2e` will not run side-by-side.                 | `number`                                   | `4200`   |
+
+## Creating a single test file
+
+Puppeteer Angular Schematic exposes a method to create a single test file.
+
+```bash
+ng generate @puppeteer/ng-schematics:test "<TestName>"
+```
+
+### Running test server and dev server at the same time
+
+By default the E2E test will run the app on the same port as `ng start`.
+To avoid this you can specify the port the an the `angular.json`
+Update either `e2e` or `puppeteer` (depending on the initial setup) to:
+
+```json
+{
+  "e2e": {
+    "builder": "@puppeteer/ng-schematics:puppeteer",
+    "options": {
+      "commands": [...],
+      "devServerTarget": "sandbox:serve",
+      "testingFramework": "<TestingFramework>",
+      "port": 8080
+    },
+    ...
+}
+```
+
+Now update the E2E test file `utils.ts` baseUrl to:
+
+```ts
+const baseUrl = 'http://localhost:8080';
+```
+
+## Contributing
+
+Check out our [contributing guide](https://pptr.dev/contributing) to get an overview of what you need to develop in the Puppeteer repo.
+
+### Sandbox
+
+For easier development we provide a script to auto-generate the Angular project to test against. Simply run:
+
+```bash
+npm run sandbox -- --init
+```
+
+After that to run `@puppeteer/ng-schematics` against the Sandbox Angular project run:
+
+```bash
+npm run sandbox
+# or to auto-build and then run schematics
+npm run sandbox -- --build
+```
+
+To run the creating of single test schematic:
+
+```bash
+npm run sandbox:test
+```
+
+### Unit Testing
+
+The schematics utilize `@angular-devkit/schematics/testing` for verifying correct file creation and `package.json` updates. To execute the test suit:
+
+```bash
+npm run test
+```

packages/ng-schematics/README.md

@@ -6,7 +6,7 @@ Adds Puppeteer-based e2e tests to your Angular project.
 
 Run the command below in an Angular CLI app directory and follow the prompts.
 
-_Note this will add the schematic as a dependency to your project._
+> Note this will add the schematic as a dependency to your project.
 
 ```bash
 ng add @puppeteer/ng-schematics

tools/generate_docs.ts

@@ -52,7 +52,7 @@ function spliceIntoSection(
 }
 
 (async () => {
-  const job1 = job('', async ({inputs, outputs}) => {
+  const copyMain = job('Copy main page', async ({inputs, outputs}) => {
     await copyFile(inputs[0]!, outputs[0]!);
   })
     .inputs(['README.md'])
@@ -60,50 +60,53 @@ function spliceIntoSection(
     .build();
 
   // Chrome Versions
-  const job2 = job('', async ({inputs, outputs}) => {
+  const updateSupportedList = job(
-    let content = await readFile(inputs[2]!, {encoding: 'utf8'});
+    'Update the Chrome supported list',
-    const versionModulePath = join('..', inputs[0]!);
+    async ({inputs, outputs}) => {
-    const {versionsPerRelease} = await import(versionModulePath);
+      let content = await readFile(inputs[2]!, {encoding: 'utf8'});
-    const versionsArchived = JSON.parse(await readFile(inputs[1]!, 'utf8'));
+      const versionModulePath = join('..', inputs[0]!);
+      const {versionsPerRelease} = await import(versionModulePath);
+      const versionsArchived = JSON.parse(await readFile(inputs[1]!, 'utf8'));
 
-    // Generate versions
+      // Generate versions
-    const buffer: string[] = [];
+      const buffer: string[] = [];
-    for (const [chromiumVersion, puppeteerVersion] of versionsPerRelease) {
+      for (const [chromiumVersion, puppeteerVersion] of versionsPerRelease) {
-      if (puppeteerVersion === 'NEXT') {
+        if (puppeteerVersion === 'NEXT') {
-        continue;
+          continue;
-      }
+        }
-      if (versionsArchived.includes(puppeteerVersion.substring(1))) {
+        if (versionsArchived.includes(puppeteerVersion.substring(1))) {
-        if (semver.gte(puppeteerVersion, '20.0.0')) {
+          if (semver.gte(puppeteerVersion, '20.0.0')) {
+            buffer.push(
+              `  * [Chrome for Testing](https://goo.gle/chrome-for-testing) ${chromiumVersion} - [Puppeteer ${puppeteerVersion}](https://pptr.dev/${puppeteerVersion.slice(
+                1
+              )})`
+            );
+          } else {
+            buffer.push(
+              `  * Chromium ${chromiumVersion} - [Puppeteer ${puppeteerVersion}](https://github.com/puppeteer/puppeteer/blob/${puppeteerVersion}/docs/api/index.md)`
+            );
+          }
+        } else if (semver.lt(puppeteerVersion, '15.0.0')) {
           buffer.push(
-            `  * [Chrome for Testing](https://goo.gle/chrome-for-testing) ${chromiumVersion} - [Puppeteer ${puppeteerVersion}](https://pptr.dev/${puppeteerVersion.slice(
+            `  * Chromium ${chromiumVersion} - [Puppeteer ${puppeteerVersion}](https://github.com/puppeteer/puppeteer/blob/${puppeteerVersion}/docs/api.md)`
+          );
+        } else if (semver.gte(puppeteerVersion, '15.3.0')) {
+          buffer.push(
+            `  * Chromium ${chromiumVersion} - [Puppeteer ${puppeteerVersion}](https://pptr.dev/${puppeteerVersion.slice(
               1
             )})`
           );
         } else {
           buffer.push(
-            `  * Chromium ${chromiumVersion} - [Puppeteer ${puppeteerVersion}](https://github.com/puppeteer/puppeteer/blob/${puppeteerVersion}/docs/api/index.md)`
+            `  * Chromium ${chromiumVersion} - Puppeteer ${puppeteerVersion}`
           );
         }
-      } else if (semver.lt(puppeteerVersion, '15.0.0')) {
-        buffer.push(
-          `  * Chromium ${chromiumVersion} - [Puppeteer ${puppeteerVersion}](https://github.com/puppeteer/puppeteer/blob/${puppeteerVersion}/docs/api.md)`
-        );
-      } else if (semver.gte(puppeteerVersion, '15.3.0')) {
-        buffer.push(
-          `  * Chromium ${chromiumVersion} - [Puppeteer ${puppeteerVersion}](https://pptr.dev/${puppeteerVersion.slice(
-            1
-          )})`
-        );
-      } else {
-        buffer.push(
-          `  * Chromium ${chromiumVersion} - Puppeteer ${puppeteerVersion}`
-        );
       }
-    }
+      content = spliceIntoSection('version', content, buffer.join('\n'));
-    content = spliceIntoSection('version', content, buffer.join('\n'));
 
-    await writeFile(outputs[0]!, content);
+      await writeFile(outputs[0]!, content);
-  })
+    }
+  )
     .inputs([
       'versions.js',
       'website/versionsArchived.json',
@@ -112,14 +115,27 @@ function spliceIntoSection(
     .outputs(['docs/chromium-support.md'])
     .build();
 
-  await Promise.all([job1, job2]);
+  const copyNgSchematics = job(
+    'Copy @puppeteer/ng-schematics main page',
+    async ({inputs, outputs}) => {
+      await copyFile(inputs[0]!, outputs[0]!);
+    }
+  )
+    .inputs(['packages/ng-schematics/README.md'])
+    .outputs(['docs/ng-schematics.md'])
+    .build();
+
+  await Promise.all([copyMain, updateSupportedList, copyNgSchematics]);
 
   // Generate documentation
-  const puppeteerDocs = job('', async ({inputs, outputs}) => {
+  const puppeteerDocs = job(
-    await rm(outputs[0]!, {recursive: true, force: true});
+    'Generate Puppeteer API markdown',
-    generateDocs(inputs[0]!, outputs[0]!);
+    async ({inputs, outputs}) => {
-    spawnAndLog('prettier', '--ignore-path', 'none', '--write', 'docs');
+      await rm(outputs[0]!, {recursive: true, force: true});
-  })
+      generateDocs(inputs[0]!, outputs[0]!);
+      spawnAndLog('prettier', '--ignore-path', 'none', '--write', 'docs');
+    }
+  )
     .inputs([
       'docs/puppeteer.api.json',
       'tools/internal/custom_markdown_documenter.ts',
@@ -127,11 +143,14 @@ function spliceIntoSection(
     .outputs(['docs/api'])
     .build();
 
-  const browsersDocs = job('', async ({inputs, outputs}) => {
+  const browsersDocs = job(
-    await rm(outputs[0]!, {recursive: true, force: true});
+    'Generate @puppeteer/browsers API markdown',
-    generateDocs(inputs[0]!, outputs[0]!);
+    async ({inputs, outputs}) => {
-    spawnAndLog('prettier', '--ignore-path', 'none', '--write', 'docs');
+      await rm(outputs[0]!, {recursive: true, force: true});
-  })
+      generateDocs(inputs[0]!, outputs[0]!);
+      spawnAndLog('prettier', '--ignore-path', 'none', '--write', 'docs');
+    }
+  )
     .inputs([
       'docs/browsers.api.json',
       'tools/internal/custom_markdown_documenter.ts',
@@ -141,11 +160,14 @@ function spliceIntoSection(
 
   await Promise.all([puppeteerDocs, browsersDocs]);
 
-  await job('', async ({inputs, outputs}) => {
+  await job(
-    const readme = await readFile(inputs[1]!, 'utf-8');
+    'Update main @puppeteer/browsers page',
-    const index = await readFile(inputs[0]!, 'utf-8');
+    async ({inputs, outputs}) => {
-    await writeFile(outputs[0]!, index.replace('# API Reference\n', readme));
+      const readme = await readFile(inputs[1]!, 'utf-8');
-  })
+      const index = await readFile(inputs[0]!, 'utf-8');
+      await writeFile(outputs[0]!, index.replace('# API Reference\n', readme));
+    }
+  )
     .inputs(['docs/browsers-api/index.md', 'packages/browsers/README.md'])
     .outputs(['docs/browsers-api/index.md'])
     .build();

website/package.json

@@ -15,9 +15,9 @@
     "archive": "node archive.js"
   },
   "dependencies": {
-    "@docusaurus/core": "2.4.0",
+    "@docusaurus/core": "2.4.1",
-    "@docusaurus/plugin-client-redirects": "2.4.0",
+    "@docusaurus/plugin-client-redirects": "2.4.1",
-    "@docusaurus/preset-classic": "2.4.0",
+    "@docusaurus/preset-classic": "2.4.1",
     "@mdx-js/react": "1.6.22",
     "clsx": "1.2.1",
     "prism-react-renderer": "1.3.5",
@@ -25,7 +25,7 @@
     "react-dom": "17.0.2"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "2.4.0",
+    "@docusaurus/module-type-aliases": "2.4.1",
     "swc-loader": "0.2.3"
   },
   "browserslist": {

website/sidebars.js

@@ -22,6 +22,7 @@ module.exports = {
         'guides/debugging',
       ],
     },
+    'ng-schematics',
     'chromium-support',
     'troubleshooting',
     'contributing',