mirror of
https://github.com/puppeteer/puppeteer
synced 2024-06-14 14:02:48 +00:00
docs: add ng-schematics page (#10459)
This commit is contained in:
Nikolay Vitkov
GitHub
parent
a43b346bfc
commit
10fa352102
107
docs/ng-schematics.md
Normal file
107
docs/ng-schematics.md
Normal file
@ -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
|
||||
```
|
||||
@ -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
|
||||
|
||||
@ -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}) => {
|
||||
let content = await readFile(inputs[2]!, {encoding: 'utf8'});
|
||||
const versionModulePath = join('..', inputs[0]!);
|
||||
const {versionsPerRelease} = await import(versionModulePath);
|
||||
const versionsArchived = JSON.parse(await readFile(inputs[1]!, 'utf8'));
|
||||
const updateSupportedList = job(
|
||||
'Update the Chrome supported list',
|
||||
async ({inputs, outputs}) => {
|
||||
let content = await readFile(inputs[2]!, {encoding: 'utf8'});
|
||||
const versionModulePath = join('..', inputs[0]!);
|
||||
const {versionsPerRelease} = await import(versionModulePath);
|
||||
const versionsArchived = JSON.parse(await readFile(inputs[1]!, 'utf8'));
|
||||
|
||||
// Generate versions
|
||||
const buffer: string[] = [];
|
||||
for (const [chromiumVersion, puppeteerVersion] of versionsPerRelease) {
|
||||
if (puppeteerVersion === 'NEXT') {
|
||||
continue;
|
||||
}
|
||||
if (versionsArchived.includes(puppeteerVersion.substring(1))) {
|
||||
if (semver.gte(puppeteerVersion, '20.0.0')) {
|
||||
// Generate versions
|
||||
const buffer: string[] = [];
|
||||
for (const [chromiumVersion, puppeteerVersion] of versionsPerRelease) {
|
||||
if (puppeteerVersion === 'NEXT') {
|
||||
continue;
|
||||
}
|
||||
if (versionsArchived.includes(puppeteerVersion.substring(1))) {
|
||||
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}) => {
|
||||
await rm(outputs[0]!, {recursive: true, force: true});
|
||||
generateDocs(inputs[0]!, outputs[0]!);
|
||||
spawnAndLog('prettier', '--ignore-path', 'none', '--write', 'docs');
|
||||
})
|
||||
const puppeteerDocs = job(
|
||||
'Generate Puppeteer API markdown',
|
||||
async ({inputs, outputs}) => {
|
||||
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}) => {
|
||||
await rm(outputs[0]!, {recursive: true, force: true});
|
||||
generateDocs(inputs[0]!, outputs[0]!);
|
||||
spawnAndLog('prettier', '--ignore-path', 'none', '--write', 'docs');
|
||||
})
|
||||
const browsersDocs = job(
|
||||
'Generate @puppeteer/browsers API markdown',
|
||||
async ({inputs, outputs}) => {
|
||||
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}) => {
|
||||
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));
|
||||
})
|
||||
await job(
|
||||
'Update main @puppeteer/browsers page',
|
||||
async ({inputs, outputs}) => {
|
||||
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();
|
||||
|
||||
1213
website/package-lock.json
generated
1213
website/package-lock.json
generated
File diff suppressed because it is too large
Load Diff
@ -15,9 +15,9 @@
|
||||
"archive": "node archive.js"
|
||||
},
|
||||
"dependencies": {
|
||||
"@docusaurus/core": "2.4.0",
|
||||
"@docusaurus/plugin-client-redirects": "2.4.0",
|
||||
"@docusaurus/preset-classic": "2.4.0",
|
||||
"@docusaurus/core": "2.4.1",
|
||||
"@docusaurus/plugin-client-redirects": "2.4.1",
|
||||
"@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": {
|
||||
|
||||
@ -22,6 +22,7 @@ module.exports = {
|
||||
'guides/debugging',
|
||||
],
|
||||
},
|
||||
'ng-schematics',
|
||||
'chromium-support',
|
||||
'troubleshooting',
|
||||
'contributing',
|
||||
|
||||
Loading…
Reference in New Issue
Block a user