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 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.