Commit Graph

67 Commits

Author SHA1 Message Date
Jack Franklin
fd857474cc
chore: fix doclint violations (#6849) 2021-02-09 11:52:35 +00:00
Jan Scheffler
5ea76e9333
feat: add page.emulateNetworkConditions (#6759) 2021-01-21 10:00:57 +01:00
Jack Franklin
e655bb6ca2
chore(agnostification): split up root Puppeteer class (#6504)
The `Puppeteer` class had two concerns:

* connect to an existing browser
* launch a new browser

The first of those concerns is needed in all environments, but the
second is only needed in Node.
https://github.com/puppeteer/puppeteer/pull/6484 landing enabled us to
pull the `Puppeteer` class apart into two:

1. `Puppeteer` which hosts the behaviour for connecting to existing
   browsers.
2. `PuppeteerNode`, which extends `Puppeteer` and also adds the ability
   to launch a new browser.

This is a non-breaking change, because Node users will still get an
instance of a class with all the methods they expect, but it'll be a
`PuppeteerNode` rather than `Puppeteer`. I don't expect this to cause
people any issues.

We also now have new files that are effectively the entry points for
Puppeteer:

* `node.ts`: the main entry point for Puppeteer on Node.
* `web.ts`: the main entry point for Puppeteer on the web.
* `node-puppeteer-core.ts`: for those using puppeteer-core (which only
  exists in Node, not on the web).
2020-10-13 16:19:26 +01:00
Jack Franklin
4846b8723c
chore(agnostification): split up launcher class (#6484)
The `Launcher` class was serving two purposes:

1. Launch browsers
2. Connect to browsers

Number 1) only needs to be done in Node land, but 2) is agnostic; in a
browser version of Puppeteer we'll need the ability to connect over a
websocket to send commands back and forth.

As part of the agnostification work we needed to split the `Launcher` up
so that the connection part can be made agnostic. Additionally, I
removed dependencies on `https`, `http` and `URL` from Node, instead
leaning on fetch (via `node-fetch` if in Node land) and the browser
`URL` API (which was added to Node in Node 10).
2020-10-12 10:08:57 +01:00
Jack Franklin
13f8fe6e16
chore(docs): page.emulateVisionDeficiency docs (#6231)
This commit also removes our own custom type for defining the vision
deficiencies and uses the protocol's type. Now we generate docs for
those we get the docs generated for free for these. This is better than
us duplicating values for types in doc comments and having them become
outdated. If we use the protocol types directly then we ensure we're up
to date and in-sync.

Long term the docs will also link to the devtools-protocol viewer.
2020-07-22 10:04:53 +01:00
Jack Franklin
f1a6b8d66d
chore: vendor Mitt & update project structure (#6209)
* chore: vendor Mitt into src/common/third-party

As discussed in #6203 we need to vendor our common dependencies in so
that when we ship an ESM build all imports point to file paths and do
not rely on Node resolution (e.g. a browser does not understand `import
mitt from 'mitt'`).
2020-07-14 16:57:29 +01:00
Jack Franklin
31309b0e20
chore: use devtools-protocol package (#6172)
* chore: Use devtools-protocol package

Rather than maintain our own protocol we can instead use the devtools-protocol package and pin it to the version of Chromium that Puppeteer is shipping with.

The only changes are naming changes between the bespoke protocol that Puppeteer created and the devtools-protocol one.
2020-07-10 11:51:52 +01:00
Jack Franklin
f666be3f5f
chore: remove src/api.ts (#6191)
Now the async hooks helper is gone api.ts was only used by the coverage
tools and by doclint.

DocLint is nearing the end of its lifespan with the TSDoc work, so I
focused on how best to define a list of modules for the coverage
tooling. They define an object of classes, and the path to that module.
They need the full path because we also check if the module exports any
events that need to be emitted - the coverage tool asserts that the
emitting of those events is also tested.

It's not _great_ that DocLint relies on a constant defined in the
coverage utils, but it should only be this way for a short period of
time and no one is actively working on DocLint (bar the effort to remove
it) so I don't think this is worth worrying about.

This change also broke the DocLint tests; based on the fact that DocLint is on its way out it doesn't feel worth fixing the tests, so this commit also removes them.
2020-07-10 10:07:28 +01:00
Jack Franklin
24cb6a28ad
chore(docs): document Frame class (#6188)
* chore: document Frame class
2020-07-09 14:22:58 +01:00
Christian Bromann
e67a860eb0
feat: add Mouse#wheel (#6141) 2020-07-06 09:27:17 +02:00
Jack Franklin
f7857d27c4
chore(docs): document HTTPRequest with TSDoc (#6146)
* chore(docs): document HTTPRequest with TSDoc

* doclint

* example
2020-07-03 14:28:45 +01:00
Jack Franklin
29f7e161b1
chore(docs): reduce warnings when generating docs (#6138)
* chore(docs): reduce warnings when generating docs

This is a bunch of small miscellaneous fixes that reduce the amount of
warnings logged when generating our new docs. The long term goal is to
get this list down to 0 warnings, but I'll do it in multiple PRs.

* satisfy doclint
2020-07-02 12:15:39 +01:00
Jack Franklin
6474edb9ba
feat(types): add types for $eval (#6135)
This pulls in the types (based on the DefinitelyTyped repo) for
`page.$eval` (and the `$eval` method on other classes). The `$eval`
method is quite hard to type due to the way we wrap and unwrap
ElementHandles that are passed to / returned from the `pageFunction`
that users provide.

Longer term we can improve the types by providing type overloads as
DefinitelyTyped does but I've deferred that for now (see the `TODO` in
the code for more details).
2020-07-02 10:09:34 +01:00
Yang Guo
123c377512
docs(new): Add TSDoc to Coverage class (#6106) 2020-06-29 09:53:28 +01:00
Jack Franklin
37f6032003
feat(api): remove emulateMedia method (#6084)
It has been deprecated for a while. In the next breaking release let's remove it.

BREAKING CHANGE: swap to `emulateMediaType` instead.
2020-06-23 16:27:37 +01:00
Peter Marshall
ccae54644c
docs(new): migrate Browser docs to TSDoc (#6070) 2020-06-23 07:19:15 +02:00
Alex Rudenko
6657364364
docs(new): migrate ElementHandle to TSDoc (#6073)
* docs(new): migrate ElementHandle to TSDoc

Co-authored-by: Alex Rudenko <alexrudenko@chromium.org>
2020-06-22 17:21:57 +02:00
Jack Franklin
b659969a38
chore: migrate away from Node's EventEmitter (#5979) 2020-06-15 11:52:19 +01:00
Jack Franklin
8a099a0c2c
docs: replace @return with @returns (#6006)
The former is not understood by TSDoc.
2020-06-12 12:38:24 +02:00
Jack Franklin
0b3d52a70e
feat(new-docs): add TSDoc comments to Accessibility (#5971)
* feat(new-docs): add tsdoc to `Accessibility`
2020-06-05 15:20:11 +01:00
Jack Franklin
309d8115c3
chore: Revert Mitt due to breaking changes (#5952)
Replacing the Node EventEmitter with Mitt caused more problems than
anticipated for end users due to the API differences and the amount of
people who relied on the EventEmitter API. In hindsight this clearly
should have been explored more and then released as a breaking v4.

This commit rolls us back to the built in Node EventEmitter library
which we can release to get everyone back on stable builds. We can then
consider our approach to migrating to Mitt and when we do do that we can
release it as a breaking change and properly document the migration
strategy and approach.
2020-06-02 09:32:02 +01:00
Jack Franklin
b874cacaef
chore: rename Worker to WebWorker (#5941)
To avoid TS name conflicts.
2020-05-29 12:57:54 +01:00
Jack Franklin
1d4d25a0f3
Use Mitt as the Event Emitter (#5907)
* chore: migrate to Mitt as the EventEmitter

This commit moves us to using Mitt [1] for the event emitter in
Puppeteer. This removes our dependency to Node's EventEmitter which is
part of a larger stream of work to enable a Puppeteer-web version that
doesn't depend on Node.

There are no large breaking changes as we support the main methods that
EventEmitter had, but it also provides some methods that Puppeteer
didn't use. Technically end users could depend on this but it's
unlikely.

[1]: https://github.com/developit/mitt
2020-05-29 09:59:26 +01:00
Jack Franklin
8e8a9df3dd
chore: rename Request class to HTTPRequest (#5934)
It conflicts with an inbuilt TypeScript `Request` type so can cause
confusion when in TS land. Note: `Response.ts` and `Worker.ts` also
suffer from this; PRs to rename them are incoming.
2020-05-29 09:38:40 +01:00
Mathias Bynens
7eab7f8dd9
feat(api): add page.emulateVisionDeficiency(type) (#5901)
Design doc: https://goo.gle/devtools-cvd
2020-05-26 17:14:20 +02:00
Jack Franklin
4fdb1e3cab
chore: add Prettier (#5825) 2020-05-07 12:54:55 +02:00
Jack Franklin
ae7483d5cf
chore: remove src/externs.d.ts (#5811)
* chore: remove src/externs.d.ts

It defined global types that we don't want to use, and instead we move
to using interfaces that we import and reference just like with any
other interface.

This means other than Protocol (which I think is fine to leave as is),
there are no other magic global types and you have to import any types
or interfaces that you want.
2020-05-06 14:23:07 +01:00
Jack Franklin
de4f08dc52
chore: migrate src/Page.js to TypeScript (#5809)
* chore: migrate src/Page.js to TypeScript

The final one! This is a huge file and needs to be split up and tidied,
but for now I've left all the definitions in place and converted types
accordingly.

There's some additional tidying we can do now every `src` file is TS,
but I'll leave that for another PR to avoid this one getting any bigger.

Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2020-05-05 13:53:22 +01:00
Jack Franklin
890c215142
chore: migrate src/Puppeteer to TypeScript (#5789)
* chore: migrate src/Puppeteer to TypeScript.

* fix api js
2020-05-05 09:36:44 +01:00
Jack Franklin
ec91ecaf0b
chore: migrate src/Launcher to TypeScript (#5775) 2020-04-30 13:45:58 +01:00
Jack Franklin
8654d630ad
chore: migrate src/NetworkManager to TypeScript (#5774) 2020-04-30 11:15:27 +01:00
Jack Franklin
8a5008e30b
chore: migrate src/FrameManager to TypeScript (#5773) 2020-04-29 13:28:16 +02:00
Jack Franklin
06d62c0165
chore: migrate src/Browser to TS (#5761) 2020-04-28 14:26:37 +02:00
Jack Franklin
1358b45fca
chore: migrate src/LifecycleWatcher (#5734) 2020-04-27 10:03:33 +01:00
Jack Franklin
18238280df
chore: migrate src/Tracing to TypeScript (#5723) 2020-04-23 13:51:48 +02:00
Jack Franklin
133abb07cf
chore: migrate src/Input to typescript (#5710)
* chore: migrate src/Input to typescript

This moves `Keyboard`, `Mouse` and `Touchscreen` to TypeScript. We gain
some nice TS benefits here; by creating a type for all the keycodes we
support we can type the input args as that rather than `string` which
will hopefully save some users some debugging once we ship our TS types
in a future version.

* Remove from externs file

* Update utils/doclint/check_public_api/index.js

Co-Authored-By: Mathias Bynens <mathias@qiwi.be>

Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2020-04-22 15:44:04 +01:00
Jack Franklin
e3922ea1f3
chore: enforce consistent spacing around object curlys (#5700)
The codebase was incredibly inconsistent with the use of spacing around
curly braces, e.g.:

```
// this?
const a = {b: 1}
// or?
const a = { b: 1 }
```

This extended into import statements also. Google's styleguide is no
spacing, so we're going with that.
2020-04-21 10:40:04 +01:00
Jack Franklin
a614bc45aa
chore: migrate src/Connection to TypeScript (#5694)
* chore: migrate `src/Connection` to TypeScript

This commit migrates `src/Connection` to TypeScript. It also changes its
exports to be ESM because TypeScript's support for exporting values to
use as types via CommonJS is poor (by design) and so rather than battle
that it made more sense to migrate the file to ESM.

The good news is that TypeScript is still outputting to `lib/` as
CommonJS, so the fact that we author in ESM is actually not a breaking
change at all.

So going forwards we will:

* migrate TS files to use ESM for importing and exporting
* continue to output to `lib/` as CommonJS
* continue to use CommonJS requires when in a `src/*.js` file

I'd also like to split `Connection.ts` into two; I think the
`CDPSession` class belongs in its own file, but I will do that in
another PR to avoid this one becoming bigger than it already is.

I also turned off `@typescript-eslint/no-use-before-define` as I don't
think it was adding value and Puppeteer's codebase seems to have a style
of declaring helper functions at the bottom which is fine by me.

Finally, I updated the DocLint tool so it knows of expected method
mismatches. It was either that or come up with a smart way to support
TypeScript generics in DocLint and given we don't want to use DocLint
that much longer that didn't feel worth it.

* Fix params being required
2020-04-21 09:20:25 +01:00
Jack Franklin
efe561e112
chore: fix DocLint method diffing (#5594)
Our logic around missing methods wasn't quite right; if there is no set of missing methods for a class it _is_ an error and we still need to report it, we don't want to `continue`.
2020-04-06 12:36:28 +02:00
Jack Franklin
4ee2c43f06
chore: fix Page.emulateMedia doclint failure (#5584)
This is expected as we now alias `emulateMedia` in `index.js` which isn't a file checked by DocLint. We alias there to avoid having the function overriden by the `asyncInstallHooks` code.

This commit updates doclint to know about methods that we expect it will find are missing and in that case just skip over them. We should only do this for methods where we plan to deprecate them or we have to define them in an odd way to work around some problem (and if that's the case long term we should fix that problem so we can define them as normal).

Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2020-04-06 10:38:05 +02:00
Andrey Lushnikov
62da2366c6
chore: introduce //lib/api.js (#3835)
Introduce `//lib/api.js` that declares a list of publicly exposed
classes.

The `//lib/api.js` list superceedes dynamic `helper.tracePublicAPI()` calls
and is used in the following places:
- [ASYNC STACKS]: generate "async stacks" for publicy exposed API in `//index.js`
- [COVERAGE]: move coverage support from `//lib/helper` to `//test/utils`
- [DOCLINT]: get rid of 'exluded classes' hardcoded list

This will help us to re-use our coverage and doclint infrastructure
for Puppeteer-Firefox.

Drive-By: it turns out we didn't run coverage for `SecurityDetails`
class, so we lack coverage for a few methods there. These are excluded
for now, sanity tests will be added in a follow-up.
2019-01-25 23:21:14 -05:00
Andrey Lushnikov
4ac00caf9d
refactor: split out DOMWorld from Frame (#3780)
This patch splits out `IsolatedWorld` class from Frame.
The `IsolatedWorld` abstraction is an execution context
with a designated set of DOM wrappers.

References #2671
2019-01-15 17:21:23 -08:00
Joel Einbinder
a0cbaf39ab chore(types): lint the api docs with typescript (#3577) 2018-11-21 14:49:08 -08:00
Andrey Lushnikov
927d0f443b
feat(page): support waitUntil option for page.setContent (#3557)
This patch teaches `page.setContent` to await resources in
the new document.

**NOTE**: This patch changes behavior: currently, `page.setContent`
awaits the `"domcontentloaded"` event; with this patch, we can now await
other lifecycle events, and switched default to the `"load"` event.

The change is justified since current behavior made `page.setContent`
unusable for its main designated usecases, pushing our client
to use [dataURL workaround](https://github.com/GoogleChrome/puppeteer/issues/728#issuecomment-334301491).

Fixes #728
2018-11-20 15:32:46 -08:00
Joel Einbinder
9ba3261571 feat(accessibility): snapshot the accessibility tree (#3470)
This adds `page.accessibility.snapshot()`. It serializes and returns the accessibility tree for the page. By default, uninteresting nodes are filtered out of the snapshot.

fixes #2033
2018-11-01 18:54:51 -07:00
Andrey Lushnikov
1b2c8113ba
refactor: move Connection to use ConnectionTransport (#3217)
Currently connection assumes that transport is a websocket
and tries to handle websocket-related errors.

This patch:
- moves ConnectionTransport interface to use callbacks instead
  of events. This way it could be used in browser context as well.
- introduces WebSocketTransport that implements ConnectionTransport
  interface for ws.

This is a preparation step for 2 things:
- exposing `transport` option in the `puppeteer.connect` method
- better support for `browserify`

References #2119
2018-09-07 21:36:16 +01:00
Andrey Lushnikov
204c7ec8c4
feat: introduce puppeteer/Errors (#3056)
This patch adds a new require, `puppeteer/Errors`, that
holds all the Puppeteer-specific error classes.

Currently, the only custom error class we use is `TimeoutError`. We'll
expand in future with `CrashError` and some others.

Fixes #1694.
2018-08-09 16:51:12 -07:00
Andrey Lushnikov
e8a085ccfb
feat(appMode): support pipes for appMode (#2032)
This patch starts using pipes as a transport to
the browser instance instead of websocket.
2018-02-14 17:51:29 -08:00
Andrey Lushnikov
a363a733b7
feat: Introduce BrowserFetcher class (#1983)
This patch introduces `BrowserFetcher` class that manages
downloaded versions of products.

This patch:
- shapes Downloader API to be minimal yet usable for our needs. This
  includes removing such methods as `Downloader.supportedPlatforms` and
  `Downloader.defaultRevision`.
- makes most of the fs-related methods in Downloader async. The only
  exception is the `Downloader.revisionInfo`: it has stay sync due to the
  `pptr.executablePath()` method being sync.
- updates `install.js` and `utils/check_availability.js` to use new API
- finally, renames `Downloader` into `BrowserFetcher`

Fixes #1748.
2018-02-07 12:31:53 -05:00
Andrey Lushnikov
5368051610
feat: expose raw devtools protocol connection (#1770)
feat: expose raw devtools protocol connection

This patch introduces `target.createCDPSession` method that
allows directly communicating with the target over the
Chrome DevTools Protocol.

Fixes #31.
2018-01-10 19:33:22 -08:00