Commit Graph

1879 Commits

Author SHA1 Message Date
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
221d172843
chore: add typecheck command (#6140)
If you want to run TypeScript only to verify that it's typechecking correctly, this command is quicker as it doesn't output CJS and ESM to disk. Useful for checking during development.
2020-07-02 13:04:55 +02: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
Jack Franklin
8370ec88ae
feat(types): add (and fix) evaluateHandle types (#6130)
This change started as a small change to pull types from DefinitelyTyped over to
Puppeteer for the `evaluateHandle` function but instead ended up also fixing
what looks to be a long standing issue with our existing documentation.

`evaluateHandle` can in fact return an `ElementHandle` rather than a `JSHandle`.
Note that `ElementHandle` extends `JSHandle` so whilst the docs are technically
correct (all ElementHandles are JSHandles) it's confusing because JSHandles
don't have methods like `click` on them, but ElementHandles do.

if you return something that is an HTML element:

```
const button = page.evaluateHandle(() => document.querySelector('button'));
// this is an ElementHandle, not a JSHandle
```

Therefore I've updated the original docs and added a large explanation to the
TSDoc for `page.evaluateHandle`.

In TypeScript land we'll assume the function will return a `JSHandle` but you
can tell TS otherwise via the generic argument, which can only be `JSHandle`
(the default) or `ElementHandle`:

```
const button = page.evaluateHandle<ElementHandle>(() => document.querySelector('button'));
```
2020-07-01 12:44:08 +01:00
Jack Franklin
3c0dc45e47
chore: update Windows skipped tests. (#6133)
The headful one I'm permanently skipping as I don't know what the issue is and I can't debug without getting my hands on a Windows machine. If anyone has one or is able to help, that'd be great!

The other I'm deferring another month and will ping the FF folks :)
2020-07-01 11:28:13 +01:00
Jack Franklin
9f198626f8
chore(docs): mark JSHandle properties as internal (#6126) 2020-06-30 15:56:37 +01:00
Mathias Bynens
8026ca9514
docs(api): fix overview diagram for pptr.dev (#6128)
We need to serve the image from user-images.githubusercontent.com for it to work properly on pptr.dev. This broke when merging #5947.

Fixes #6127.
2020-06-30 15:56:26 +01:00
Jack Franklin
9d79cc89cb
chore: fix Firefox install checker (#6129)
I think when the FF version changes this check breaks - let's just make
it check that a version installed rather than the specific version else
this will happen on a continuing basis.
2020-06-30 15:52:53 +01:00
Jack Franklin
1f5e333f00
chore: Don't store revisions in package.json (#6109)
* chore: Don't store revisions in `package.json`

It's quite messy to have to require the `package.json` file in multiple
places purely to find out what revision of a given browser we want to
use. We can also achieve better type safety by placing it in an actual
source file.

This commit makes that change and also tidies up our reliance on
`package.json` within the source code generally; we now only use it to
find the location of the Puppeteer root such that we know where to
install downloaded browsers to.

To avoid using `package.json` to parse the name of the module, we also
now explicitly have an entry point for the Puppeteer module and the
Puppeter Core module. This will make it easier in the future to ship
less code as part of core (e.g. core never needs to download a browser,
so why ship that code?). Core can also then not have any revisions based
info contained in it.

The test install script has also been updated to ensure that
puppeteer-core can be installed correctly too.

Finally, the `install` script has been moved to TypeScript for nicer
typechecking and safety. The functionality of it has not changed.
2020-06-29 16:13:24 +01:00
Yang Guo
123c377512
docs(new): Add TSDoc to Coverage class (#6106) 2020-06-29 09:53:28 +01:00
Toideng
3760302dfe
docs(api): fix broken links in api.md (#6113)
Fix broken cross-links to classes HTTPRequest and HTTPResponse.
2020-06-26 11:51:08 +02:00
Changhao Han
adeffbaac1
docs(new): migrate Page.ts to TSDoc (part 0 / 2) (#6104)
* docs(new): migrate Page.ts to TSDoc (part 0 / 2)

Co-authored-by: Changhao Han <changhaohan@chromium.org>
2020-06-26 09:24:56 +02:00
Mathias Bynens
df96f16921
docs(new): migrate JSHandle docs to TSDoc (#6102) 2020-06-25 15:49:35 +01:00
Jack Franklin
1c0009d2c0
chore(agnostic): ship CJS and ESM builds (#6095)
* chore(agnostic): ship CJS and ESM builds

For our work to enable Puppeteer in other environments (e.g. a browser)
we need to ship an ESM build. This commit changes our config to ship to
`lib/cjs` and `lib/esm` accordingly. The majority of our code stays the
same, with one small fix for the CJS build to ensure that we ship a
version that lets you `require('puppeteer')` rather than have to
`require('puppeteer').default`. We do this with the `cjs-entry.js` which
is what the `main` field in our `package.json` points to.

We also swap to `read-pkg-up` to find the `package.json` file. This is
because the folder structure of `lib/` does not match `src/` now we ship
to `cjs` and `esm`, so you cannot rely on exact paths. This module works
up from the file to find the nearest `package.json` so it will always
find Puppeteer's `package.json`.

Note that we *do not* point any users to the ESM build. We happen to
ship those files so people who know about them can get at them but it's
not expected (nor will we actively support) that people will rely on
them. The CommonJS build is considered our main build.

We may make breaking changes to the structure of the ESM build which we
will do without requiring new major versions. For example the ESM build
currently ships all files that the CJS build does, but given we are
working on the ESM build being able to run in the browser this may
change over time.

Long term once the Node versions catch up we can ditch CJS and ship
exclusively ESM but we are not there yet.
2020-06-25 14:24:46 +01:00
Jack Franklin
46fc6ca41a
feat(types): improve typing of .evaluate() (#6096)
* feat(types): improve typing of `.evaluate()`

This is the start of the work to take the types from the
`@types/puppeteer` repository and port them into our repo so we can ship
our built-in types out the box.

This change types the `evaluate` function properly. It takes a generic
type which is the type of the function you're passing, and the arguments
and the return that you get back from the `evaluate` call are typed
correctly.
2020-06-25 13:38:01 +01:00
Jack Franklin
a4d12a2b21 chore: remove helper.promisify (#6100)
It was just re-exporting the built-in Node module so let's just import
from that directly.
2020-06-25 13:01:46 +02:00
Jack Franklin
5b6d2bfb0e docs(new): add TSDoc comments to Keyboard (#6099)
Co-authored-by: Tim van der Lippe <tvanderlippe@google.com>
2020-06-25 13:01:46 +02:00
Changhao Han
4696f7abda docs(new): migrate HTTPResponse docs to TSDoc (#6085)
Co-authored-by: Changhao Han <changhaohan@chromium.org>
2020-06-25 13:01:46 +02:00
Jack Franklin
b993adb468 chore(agnostic): Migrate DOMWorld (#6054)
DOMWorld only needs to use Node's `fs` module if you're adding a
filepath as a script/style tag. We can detect this case and run the
`require` inline such that in a browser this code won't execute.
2020-06-25 13:01:46 +02:00
Pete LePage
c1490349bc chore: remove hardcoded ?hl=en from docs (#6097) 2020-06-25 13:01:46 +02:00
Jack Franklin
48c5a8ed01 docs(new): add TSDoc comments to Puppeteer (#6032) (#6094)
Co-authored-by: Martin Splitt <mr.avgp@googlemail.com>
2020-06-25 13:01:46 +02:00
Martin Splitt
f1f7339a3b docs(new): add TSDoc comments to Puppeteer (#6032) 2020-06-25 13:01:46 +02:00
Martin Splitt
a46c78fc91 docs(new): Adds TSDoc to Tracing class (#6088)
* Adds tsdoc to Tracing class

* Updates tsdocs

Co-authored-by: martinsplitt <martin@geekonaut.de>
2020-06-25 13:01:46 +02:00
Martin Splitt
60904da4cd docs(new): migrate FileChooser docs to TSDoc (#6092)
Co-authored-by: martinsplitt <martin@geekonaut.de>
2020-06-25 13:01:36 +02:00
Jack Franklin
785551997f chore: tidy up TODO from TS tests migration (#6090)
Deleting `Node` errors in strict mode; we don't need to have this test
any more.
2020-06-25 13:01:36 +02:00
Martin Splitt
f481922175 docs(new): Adds TSDoc to Mouse class (#6086)
* Adds tsdoc to Mouse class

* Updates puppeteer class tsdoc

* docs(new): add TSDoc comments to BrowserFetcher (#6078)

* Adds tsdoc for Touchscreen (#6087)

Co-authored-by: martinsplitt <martin@geekonaut.de>

* Adds tsdoc to Mouse class

* Fixes tsdoc comment for Mouse class

Co-authored-by: martinsplitt <martin@geekonaut.de>
2020-06-25 13:01:36 +02:00
Martin Splitt
2ad42dc398 docs(new): migrate Touchscreen docs to TSDoc (#6087)
Co-authored-by: martinsplitt <martin@geekonaut.de>
2020-06-25 13:01:12 +02:00
Martin Splitt
73b97956cc
docs(new): add TSDoc comments to BrowserFetcher (#6078) 2020-06-24 09:33:19 +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
Jack Franklin
1ee379ce4d
chore: avoid disabling prettier (#6079) 2020-06-23 15:02:22 +01:00
Jack Franklin
381b0f833c
chore: declare toBeGolden to TypeScript (#6080)
Which means we can avoid all the ts-expect-errors on any `toBeGolden`
calls.
2020-06-23 15:02:09 +01:00
Jack Franklin
70a900e93b
chore: fix ESLint violation and lessen rule strictness (#6081) 2020-06-23 12:55:42 +01:00
k.zaitsev
fdc6fda46e
docs: fix effect -> affect typos (#5985) 2020-06-23 07:24:15 +02:00
Tim van der Lippe
4659ee8daa docs(new): add TSDoc comments to BrowserContext (#6066) 2020-06-23 07:22:10 +02:00
Peter Marshall
ccae54644c
docs(new): migrate Browser docs to TSDoc (#6070) 2020-06-23 07:19:15 +02:00
Jack Franklin
28797dee41
chore: migrate tests to TypeScript (#6075)
This CL migrates all the tests to TypeScript. The main benefits of this is that we start consuming our TypeScript definitions and therefore find errors in them. The act of migrating found some bugs in our definitions and now we can be sure to avoid them going forwards.

You'll notice the addition of some `TODO`s in the code; I didn't want this CL to get any bigger than it already is but I intend to follow those up once this lands. It's mostly figuring out how to extend the `expect` types with our `toBeGolden` helpers and some other slight confusions with types that the tests exposed.

Co-authored-by: Mathias Bynens <mathias@qiwi.be>
2020-06-23 07:18:46 +02:00
Stefan
2090676a55
docs: fix broken link to DeviceDescriptors.ts (#6076) 2020-06-23 06:56:31 +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
Alex Rudenko
7025f1c5ea
docs(new): migrate Target to TSDoc (#6067)
* docs(new): migrate Target to TSDoc

Co-authored-by: Alex Rudenko <alexrudenko@chromium.org>
2020-06-22 14:57:04 +02:00
Paul Lewis
819afbebf7
docs(new): migrate ConsoleMessage docs to TSDoc (#6065) 2020-06-22 13:52:39 +01:00
Alex Rudenko
983a7b67df
docs(new): migrate CDPSession to TSDoc (#6064) 2020-06-22 12:05:10 +02:00
Alex Rudenko
1cf3f06055
docs(new): migrate TimeoutError to TSDoc (#6062)
* docs(new): migrate TimeoutError to TSDoc

Co-authored-by: Alex Rudenko <alexrudenko@chromium.org>
2020-06-22 10:34:57 +02:00
Jack Franklin
ace31d6f58
chore: pin TSDoc related dependencies (#6063)
Without the API-* dependencies pinned different versions may be
installed on local machines vs CI. One of the checks we do is to check
that the checked in docs matches what is generated on CI. Therefore we
need to ensure devs locally run the exact version that CI runs such that
they generate the same output. So in this case we pin to a particular
version of the dependencies.
2020-06-22 09:16:51 +01:00
Tayo Agagu
750f5eecae
docs: fix broken link to USKeyboardLayout file (#6059)
Link in api doc to USKeyboardLayout returns a 404 (missing common folder in link)
2020-06-22 07:26:04 +02:00
Jack Franklin
e7b91a7f41
chore: enforce a max line length on comments (#6055) 2020-06-19 15:39:03 +01:00
Mathias Bynens
7978315de7
docs(new): migrate SecurityDetails docs to TSDoc (#6053) 2020-06-19 15:30:28 +02:00
Jack Franklin
7a4170fe6e
chore: remove top level errors and DeviceDescriptors (#6043)
As far as I can tell these became irrelevant as of v1.15 which added
`puppeteer.errors` and `puppeteer.devices [1]. This is a breaking change
but one that's easily mitigated. We've said that we don't consider
changes to our folder/file structure a breaking change, but we can't
really do that if we have these two top level files that we've
documented.

[1]: e3abb0aa32 (diff-522b24108d7446af4c59873472a90444)
2020-06-19 15:15:13 +02:00
Jack Franklin
5ff698ec98
chore: move index.js into src and TS-ify (#6049)
It was causing some infra issues when trying to migrate tests to
TypeScript (that's WIP in another branch that I'll have up soon). It's
unusual to have the entire src in TS except for the main file, which
then reaches into the compiled `lib` directory for the files it needs.

Much better is to move the entry point into TypeScript itself and update
the `main` entry in our `package.json` to point to the compiled output.

This also has the advantange of hooking up all the TS type defs that we
are shipping and will make that process easier too, along with making it
easier to port our tests to TypeScript.
2020-06-19 15:14:54 +02:00
Jack Franklin
940a5701ec
chore: exclude api.ts from dependency graph (#6052)
`api.ts` is a list of all our modules which is used to install a helper
and by DocLint. It's not that useful for our dep graph because it
literally requires the majority of modules so it just clutters up the diagram.
2020-06-19 13:44:49 +01:00
Jack Franklin
759b28080a
chore: upgrade to Mocha v8 (#5997)
* chore: upgrade to Mocha v8

Mocha v8 has some nice improvements and also unlocks the potential
to have parallel test runs which may speed up CI.
2020-06-18 16:26:30 +01:00