remote/doc/cdp/Usage.md

   1 # Usage
   2
   3 When using the CDP-based Remote Agent in Firefox, there are
   4 three different programs/components running simultaneously:
   5
   6 * the __client__, being the out-of-process script or library
   7   (such as Puppeteer) or web inspector frontend you use to control
   8   and retrieve information out of Firefox;
   9
  10 * the __agent__ that the client connects to which is an HTTPD living
  11   inside Firefox, facilitating communication between clients
  12   and targets;
  13
  14 * and the __target__, which is the web document being debugging.
  15
  16 Since Firefox 86 the Remote Agent ships in all Firefox releases by default.
  17
  18 To check if your Firefox binary has the Remote Agent enabled, you
  19 can look in its help message for this:
  20
  21 ```shell
  22 % ./firefox -h
  23 …
  24   --remote-debugging-port [<port>] Start the Firefox Remote Agent, which is
  25                      a low-level debugging interface based on the CDP protocol.
  26                      Defaults to listen on localhost:9222.
  27 …
  28 ```
  29
  30 When used, the Remote Agent will start an HTTP server and print a
  31 message on stderr with the location of the main target’s WebSocket
  32 listener:
  33
  34 ```shell
  35 % firefox --remote-debugging-port
  36 DevTools listening on ws://localhost:9222/devtools/browser/7b4e84a4-597f-4839-ac6d-c9e86d16fb83
  37 ```
  38
  39 The argument takes an optional `port` as value:
  40
  41 You can also instruct the Remote Agent to bind to a particular port on
  42 your system.  Therefore the argument accepts an optional value, which means
  43 that `firefox --remote-debugging-port=9989`
  44 will bind the HTTPD to port `9989`:
  45
  46 ```shell
  47 % firefox --remote-debugging-port 9989
  48 DevTools listening on ws://localhost:9989/devtools/browser/b49481af-8ad3-9b4d-b1bf-bb0cdb9a0620
  49 ```
  50
  51 If the value is missing the default port `9222` will be used.
  52
  53 When you ask the Remote Agent to listen on port 0,
  54 the system will atomically allocate an arbitrary free port:
  55
  56 ```shell
  57 % firefox --remote-debugging-port 0
  58 DevTools listening on ws://localhost:59982/devtools/browser/a12b22a9-1b8b-954a-b81f-bd31552d3f1c
  59 ```
  60
  61 Allocating an atomic port can be useful if you want to avoid race
  62 conditions.  The atomically allocated port will be somewhere in the
  63 ephemeral port range, which varies depending on your system and
  64 system configuration, but is always guaranteed to be free thus
  65 eliminating the risk of binding to a port that is already in use.