UNPKG

puppeteer-core

Version:

A high-level API to control headless Chrome over the DevTools Protocol

github.com/puppeteer/puppeteer/tree/main

puppeteer/puppeteer

58 lines (43 loc) • 2.78 kB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
# `bidi/core` `bidi/core` is a low-level layer that sits above the WebDriver BiDi transport to provide a structured API to WebDriver BiDi's flat API. In particular, `bidi/core` provides object-oriented semantics around WebDriver BiDi resources and automatically carries out the correct order of events in WebDriver BiDi through the use of events. ## Tips There are a few design decisions in this library that should be considered when developing `bidi/core`: - Required arguments are inlined as function arguments while optional arguments are put into an options object. - Function arguments are implicitly required in TypeScript, so by putting required arguments as function arguments, the semantic is automatically inherited. - The session shall never be exposed on any public method/getter on any object except the browser. Private getters are allowed. - Passing around the session is dangerous as it obfuscates the origin of the session. By only allowing it on the browser, the origin is well-defined. - `bidi/core` implements WebDriver BiDi plus its surrounding specifications. - A lot of WebDriver BiDi is not strictly written in WebDriver BiDi. Since WebDriver BiDi interacts with several other specs, there are other considerations that also influence the design of `bidi/core`. For example, for navigation, WebDriver BiDi doesn't have a concept of "nested navigation", but in practice this exists if a fragment navigation happens in a `beforeunload` hook. - `bidi/core` always follow the spec and never Puppeteer's needs. - By ensuring `bidi/core` follows the spec rather than Puppeteer's needs, we can identify the source of a bug precisely (i.e. whether the spec needs to be updated or Puppeteer needs to work around it). - `bidi/core` attempts to implement WebDriver BiDi comprehensively, but minimally. - Imagine the objects and events in WebDriver BiDi as a large [graph](<https://en.wikipedia.org/wiki/Graph_(discrete_mathematics)>) where objects are nodes and events are edges. In `bidi/core`, we always implement all edges and nodes required by a feature without skipping nodes and events (e.g. [fragment navigation -> navigation -> browsing context]; not [fragment navigation -> browsing context]). We also never compose edges (e.g. both [fragment navigation -> navigation -> browsing context] and [fragment navigation -> browsing context] must not exist; i.e. a fragment navigation event should not occur on the browsing context). This ensures that the semantics of WebDriver BiDi is carried out correctly. - This point reinforces `bidi/core` should not follow Puppeteer's needs since Puppeteer typically composes a lot of events to satisfy its needs.