diff --git a/files/en-us/web/api/cookiestoremanager/subscribe/index.md b/files/en-us/web/api/cookiestoremanager/subscribe/index.md index f53f305dcb38edd..d948ab0d2e9767c 100644 --- a/files/en-us/web/api/cookiestoremanager/subscribe/index.md +++ b/files/en-us/web/api/cookiestoremanager/subscribe/index.md @@ -10,6 +10,8 @@ browser-compat: api.CookieStoreManager.subscribe The **`subscribe()`** method of the {{domxref("CookieStoreManager")}} interface subscribes a {{domxref("ServiceWorkerRegistration")}} to cookie change events. +Duplicate subscriptions are ignored: that is, if a service worker subscribes more than once to the same cookie, it will only receive each change notification once. + ## Syntax ```js-nolint @@ -20,10 +22,10 @@ subscribe(subscriptions) - `subscriptions` - : An array of objects, each of which has the following properties: - - `name` - - : A string with the name of a cookie. - - `url` - - : A string with the url of a cookie scope. This may be narrower than the scope of the service worker registration. + - `name` {{optional_inline}} + - : A string equal to the name of a cookie. If `name` is omitted, the service worker is subscribed to change events for all cookies that are in scope. + - `url` {{optional_inline}} + - : A string equal to the URL of a cookie scope. This may be narrower than the scope of the service worker registration. If `url` is omitted, it defaults to the scope of the service worker registration. ### Return value @@ -32,23 +34,55 @@ A {{jsxref("Promise")}} that resolves with {{jsxref("undefined")}} when the subs ### Exceptions - {{jsxref("TypeError")}} - - : Thrown if the URL passed in `subscriptions` does not match the service worker registration's {{domxref("ServiceWorkerRegistration.scope","scope")}}. + - : Thrown if the `url` is not a valid URL, or doesn't start with the service worker registration's {{domxref("ServiceWorkerRegistration.scope","scope")}}. ## Examples +### Setting name and URL + In this example, the {{domxref("ServiceWorkerRegistration")}} represented by `registration` is subscribing to change events on the cookie named `"cookie1"` with a scope of `"/path1"`. ```js +// Subscribe to a specific cookie and URL const subscriptions = [{ name: "cookie1", url: `/path1` }]; await registration.cookies.subscribe(subscriptions); ``` -The URL passed to the `subscribe()` method, may be narrower than the service worker registration scope. In the following example the subscription is for `/path/one/`, so it will receive change events for changes on the first cookie, but not the second. +### Setting name only + +In this example, we set only `name` and omit `url`: the subscription applies to all cookies named `cookie1` within the service worker's scope. ```js -registration.cookies.subscribe([{ name: "cookie1", url: "/path/one/" }]); // subscription -cookieStore.set({ name: "cookie1", value: "cookie-value", path: "/path/one/" }); // receives a change event -cookieStore.set({ name: "cookie1", value: "cookie-value", path: "/path/two/" }); // does not receive a change event +// Subscribe to all cookies named "cookie1" in the registration scope +await registration.cookies.subscribe([{ name: "cookie1" }]); +``` + +### Setting URL only + +In this example we set only `url`, and omit `name`: the subscription applies to all cookies within the specified URL scope. + +```js +// Subscribe to all cookie changes within a specific path +await registration.cookies.subscribe([{ url: "/path/one/" }]); +``` + +### Subscribing to all cookies + +In this example, both `name` and `url` are omitted. The subscription applies to all cookies within the service worker's scope. + +```js +// Subscribe to all cookie changes within the entire registration scope +await registration.cookies.subscribe([{}]); +``` + +### Setting a URL outside the service worker's scope + +If the URL is outside the service worker's scope, `subscribe()` will throw a `TypeError`. + +```js example-bad +await registration.cookies.subscribe([ + { name: "cookie1", url: "/out-of-scope/" }, +]); ``` ## Specifications diff --git a/files/en-us/web/webdriver/reference/bidi/modules/index.md b/files/en-us/web/webdriver/reference/bidi/modules/index.md index ea0453a8458eaf0..0c3624649962d4d 100644 --- a/files/en-us/web/webdriver/reference/bidi/modules/index.md +++ b/files/en-us/web/webdriver/reference/bidi/modules/index.md @@ -18,7 +18,7 @@ Both command and event names use the module name as a prefix: `module_name.comma ## Commands -A command is an asynchronous operation sent from the client to the browser. Each command message you send to the browser has three fields: +A command is an asynchronous operation sent from the client to the browser. Each command message _you send_ to the browser has three fields: - `id`: A number you assign to the command. Unlike HTTP where each request waits for a response, a WebSocket connection can have multiple commands in flight at the same time and responses may arrive out of order. The `id` lets you match each response to the command that triggered it. - `method`: The command to run, in the form `module_name.command_name`. @@ -45,6 +45,12 @@ To receive events, the client must first subscribe to them using the `session.su The client can subscribe to a specific event or to all events in a module. For example, subscribing to `"browsingContext.contextCreated"` subscribes the client to that single event, while subscribing to `"browsingContext"` subscribes the client to every event in the `browsingContext` module. +Every event notification _you receive_ from the browser has three fields: + +- `type`: Always `"event"`. +- `method`: The event name, in the form `module_name.event_name`. +- `params`: An object containing the event-specific data. The structure of `params` is specific to each event. + The following is a sample event message sent by the browser when the client is subscribed to `log.entryAdded` and a console message is logged (some fields have been omitted for brevity): ```json @@ -53,11 +59,10 @@ The following is a sample event message sent by the browser when the client is s "method": "log.entryAdded", "params": { "type": "console", - "method": "log", - "realm": null, "level": "info", "text": "Hello world", - "timestamp": 1657282076037 + "timestamp": 1657282076037, + "method": "log" } } ``` diff --git a/files/en-us/web/webdriver/reference/bidi/modules/log/entryadded/index.md b/files/en-us/web/webdriver/reference/bidi/modules/log/entryadded/index.md new file mode 100644 index 000000000000000..e224703d37282cf --- /dev/null +++ b/files/en-us/web/webdriver/reference/bidi/modules/log/entryadded/index.md @@ -0,0 +1,189 @@ +--- +title: log.entryAdded event +short-title: log.entryAdded +slug: Web/WebDriver/Reference/BiDi/Modules/log/entryAdded +page-type: webdriver-event +browser-compat: webdriver.bidi.log.entryAdded_event +sidebar: webdriver +--- + +The `log.entryAdded` [event](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules#events) of the [`log`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/log) module fires when a new log entry is created in the browser, from either a console API call or an unhandled JavaScript error. + +## Event data + +The `params` field in the event notification is a log entry object. Based on the source of the log, the log entry object has different types: `"console"` or `"javascript"`. Each type may provide additional fields specific to that source. + +### Common fields + +All log entry objects include the following fields: + +- `level` + - : A string that indicates the severity of the log entry. It has one of the following values: + - `"debug"`: A debug-level message (from {{domxref("console/debug_static", "console.debug()")}} or {{domxref("console/trace_static", "console.trace()")}}). + - `"info"`: An informational message (from {{domxref("console/log_static", "console.log()")}}, {{domxref("console/info_static", "console.info()")}}, and [other console methods](/en-US/docs/Web/API/console) that don't produce a more specific level). + - `"warn"`: A warning message (from {{domxref("console/warn_static", "console.warn()")}}). + - `"error"`: An error message (from {{domxref("console/error_static", "console.error()")}} or {{domxref("console/assert_static", "console.assert()")}}). +- `source` + - : An object that identifies the [realm](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/script/getRealms) where the log entry was created. It contains the following fields: + - `realm` + - : A string that contains the ID of the realm. + - `context` {{optional_inline}} + - : A string that contains the ID of the context in which the log entry was created. + - `userContext` {{optional_inline}} + - : A string that contains the ID of the user context in which the script-related event occurred. +- `stackTrace` {{optional_inline}} + - : An object with a `callFrames` array that represents the [JavaScript stack](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/script/stackTrace) at the point the entry was created. Each item in the array is a stack frame with the following fields: `columnNumber`, `functionName`, `lineNumber`, and `url`. +- `text` + - : A string that contains the log message or `null` if not available. For console entries, it is the concatenation of all stringified arguments joined by spaces, and for JavaScript errors, it is generally the error message. + The exact format is browser-dependent, so don't rely on this value for assertions in tests. +- `timestamp` + - : A non-negative integer that represents the time when the log entry was created, in UTC, as milliseconds elapsed since the epoch ({{jsxref("Date.now()")}}). +- `type` + - : A string that identifies the source of the log entry. It has one of the following values: + - `"console"`: Indicates that the log entry was generated from a call to a console API method (for example, {{domxref("console/log_static", "console.log()")}}, {{domxref("console/warn_static", "console.warn()")}}). Log entry objects of this type include [additional fields](#console-entry-fields). + - `"javascript"`: Indicates that the log entry was generated from an unhandled JavaScript error. + +### `"console"` log entry fields + +In addition to the [common fields](#common-fields), log entry objects with `"type": "console"` also include: + +- `args` + - : An array of objects that represent the arguments passed to the console method. Each object has a `type` field (such as `"string"`, `"number"`, `"boolean"`, or `"array"`) and optional `value`, `handle`, and `internalId` fields. +- `method` + - : A string that contains the name of the console method that was called (for example, `"log"`, `"error"`, `"assert"`, `"debug"`, `"trace"`, `"warn"`). + +## Examples + +### Receiving an event for a console log + +With a [WebDriver BiDi connection](/en-US/docs/Web/WebDriver/How_to/Create_BiDi_connection) and a [subscription](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/session/subscribe) to `log.entryAdded` active, the browser sends a `log.entryAdded` event when a script evaluates `console.log("hello", [1, true, "foo"])`: + +```json +{ + "type": "event", + "method": "log.entryAdded", + "params": { + "type": "console", + "method": "log", + "source": { + "realm": "7c37f4c0-abcd-1234-ef56-789012345678", + "context": "6B3D5B3A-6571-432B-8E96-E53B5C2ECBB5" + }, + "args": [ + { + "type": "string", + "value": "hello" + }, + { + "type": "array", + "value": [ + { "type": "number", "value": 1 }, + { "type": "boolean", "value": true }, + { "type": "string", "value": "foo" } + ] + } + ], + "level": "info", + "text": "hello 1,true,foo", + "timestamp": 1712345678901, + "stackTrace": { + "callFrames": [ + { + "columnNumber": 8, + "functionName": "", + "lineNumber": 1, + "url": "https://example.com/app.js" + } + ] + } + } +} +``` + +### Receiving an event for a console warning + +With a [WebDriver BiDi connection](/en-US/docs/Web/WebDriver/How_to/Create_BiDi_connection) and a [subscription](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/session/subscribe) to `log.entryAdded` active, the browser sends a `log.entryAdded` event when a script evaluates `console.warn("something went wrong")`: + +```json +{ + "type": "event", + "method": "log.entryAdded", + "params": { + "type": "console", + "method": "warn", + "source": { + "realm": "7c37f4c0-abcd-1234-ef56-789012345678", + "context": "6B3D5B3A-6571-432B-8E96-E53B5C2ECBB5" + }, + "args": [ + { + "type": "string", + "value": "something went wrong" + } + ], + "level": "warn", + "text": "something went wrong", + "timestamp": 1712345678950, + "stackTrace": { + "callFrames": [ + { + "columnNumber": 8, + "functionName": "", + "lineNumber": 1, + "url": "https://example.com/app.js" + } + ] + } + } +} +``` + +### Receiving an event for an unhandled JavaScript error + +With a [WebDriver BiDi connection](/en-US/docs/Web/WebDriver/How_to/Create_BiDi_connection) and a [subscription](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/session/subscribe) to `log.entryAdded` active, the browser sends a `log.entryAdded` event when an unhandled JavaScript error occurs: + +```json +{ + "type": "event", + "method": "log.entryAdded", + "params": { + "type": "javascript", + "level": "error", + "source": { + "realm": "7c37f4c0-abcd-1234-ef56-789012345678", + "context": "6B3D5B3A-6571-432B-8E96-E53B5C2ECBB5" + }, + "text": "ReferenceError: undefinedVariable is not defined", + "timestamp": 1712345679100, + "stackTrace": { + "callFrames": [ + { + "columnNumber": 27, + "functionName": "", + "lineNumber": 3, + "url": "https://example.com/app.js" + }, + { + "columnNumber": 18, + "functionName": "", + "lineNumber": 3, + "url": "https://example.com/app.js" + } + ] + } + } +} +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [`session.subscribe`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/session/subscribe) command +- [`console`](/en-US/docs/Web/API/console) API diff --git a/files/en-us/web/webdriver/reference/bidi/modules/log/index.md b/files/en-us/web/webdriver/reference/bidi/modules/log/index.md index cb0eaa7009b8bc6..6bd5b40bc777a7c 100644 --- a/files/en-us/web/webdriver/reference/bidi/modules/log/index.md +++ b/files/en-us/web/webdriver/reference/bidi/modules/log/index.md @@ -7,7 +7,15 @@ browser-compat: webdriver.bidi.log sidebar: webdriver --- -The **`log`** module contains events related to logging. +The **`log`** module provides an event for monitoring browser log entries, including [console API](/en-US/docs/Web/API/console) output and unhandled JavaScript errors. + +## Commands + +The `log` module has no associated commands. + +## Events + +{{ListSubPages}} ## Specifications diff --git a/files/sidebars/webdriver.yaml b/files/sidebars/webdriver.yaml index 2015cffa6a02ae0..c13e603c18e4dd0 100644 --- a/files/sidebars/webdriver.yaml +++ b/files/sidebars/webdriver.yaml @@ -26,7 +26,10 @@ sidebar: code: true - link: /Web/WebDriver/Reference/BiDi/Modules/input code: true - - link: /Web/WebDriver/Reference/BiDi/Modules/log + - type: listSubPages + path: /Web/WebDriver/Reference/BiDi/Modules/log + link: /Web/WebDriver/Reference/BiDi/Modules/log + details: closed code: true - link: /Web/WebDriver/Reference/BiDi/Modules/network code: true diff --git a/front-matter-config.json b/front-matter-config.json index d46c25f19421796..1a5830725b06d5e 100644 --- a/front-matter-config.json +++ b/front-matter-config.json @@ -376,6 +376,7 @@ "webdriver-command", "webdriver-capability", "webdriver-error", + "webdriver-event", "reference" ] } diff --git a/package-lock.json b/package-lock.json index 1e632b8b41c8307..d54f231f75c9c2a 100644 --- a/package-lock.json +++ b/package-lock.json @@ -32,7 +32,7 @@ "imagemin-svgo": "^12.0.0", "is-svg": "^6.1.0", "lefthook": "^2.1.6", - "markdownlint-cli2": "0.22.0", + "markdownlint-cli2": "0.22.1", "markdownlint-rule-search-replace": "1.2.0", "node-html-parser": "^7.1.0", "parse-diff": "^0.12.0", @@ -3023,19 +3023,6 @@ "node": ">=22.18.0" } }, - "node_modules/cspell-config-lib/node_modules/smol-toml": { - "version": "1.6.1", - "resolved": "https://registry.npmjs.org/smol-toml/-/smol-toml-1.6.1.tgz", - "integrity": "sha512-dWUG8F5sIIARXih1DTaQAX4SsiTXhInKf1buxdY9DIg4ZYPZK5nGM1VRIYmEbDbsHt7USo99xSLFu5Q1IqTmsg==", - "dev": true, - "license": "BSD-3-Clause", - "engines": { - "node": ">= 18" - }, - "funding": { - "url": "https://github.com/sponsors/cyyynthia" - } - }, "node_modules/cspell-dictionary": { "version": "10.0.0", "resolved": "https://registry.npmjs.org/cspell-dictionary/-/cspell-dictionary-10.0.0.tgz", @@ -4820,9 +4807,9 @@ } }, "node_modules/globby": { - "version": "16.1.1", - "resolved": "https://registry.npmjs.org/globby/-/globby-16.1.1.tgz", - "integrity": "sha512-dW7vl+yiAJSp6aCekaVnVJxurRv7DCOLyXqEG3RYMYUg7AuJ2jCqPkZTA8ooqC2vtnkaMcV5WfFBMuEnTu1OQg==", + "version": "16.2.0", + "resolved": "https://registry.npmjs.org/globby/-/globby-16.2.0.tgz", + "integrity": "sha512-QrJia2qDf5BB/V6HYlDTs0I0lBahyjLzpGQg3KT7FnCdTonAyPy2RtY802m2k4ALx6Dp752f82WsOczEVr3l6Q==", "dev": true, "license": "MIT", "dependencies": { @@ -6572,13 +6559,13 @@ } }, "node_modules/markdownlint-cli2": { - "version": "0.22.0", - "resolved": "https://registry.npmjs.org/markdownlint-cli2/-/markdownlint-cli2-0.22.0.tgz", - "integrity": "sha512-mOC9BY/XGtdX3M9n3AgERd79F0+S7w18yBBTNIQ453sI87etZfp1z4eajqSMV70CYjbxKe5ktKvT2HCpvcWx9w==", + "version": "0.22.1", + "resolved": "https://registry.npmjs.org/markdownlint-cli2/-/markdownlint-cli2-0.22.1.tgz", + "integrity": "sha512-X14ZbytybDCXAViDmtN4DKLt9ZTrRn+oOrxTYlg3a65jS6QcYYbAkGPh/En2L/GDNbFYJ6lKaQSUNrrbN1bPrw==", "dev": true, "license": "MIT", "dependencies": { - "globby": "16.1.1", + "globby": "16.2.0", "js-yaml": "4.1.1", "jsonc-parser": "3.3.1", "jsonpointer": "5.0.1", @@ -6586,7 +6573,7 @@ "markdownlint": "0.40.0", "markdownlint-cli2-formatter-default": "0.0.6", "micromatch": "4.0.8", - "smol-toml": "1.6.0" + "smol-toml": "1.6.1" }, "bin": { "markdownlint-cli2": "markdownlint-cli2-bin.mjs" @@ -9000,9 +8987,9 @@ } }, "node_modules/smol-toml": { - "version": "1.6.0", - "resolved": "https://registry.npmjs.org/smol-toml/-/smol-toml-1.6.0.tgz", - "integrity": "sha512-4zemZi0HvTnYwLfrpk/CF9LOd9Lt87kAt50GnqhMpyF9U3poDAP2+iukq2bZsO/ufegbYehBkqINbsWxj4l4cw==", + "version": "1.6.1", + "resolved": "https://registry.npmjs.org/smol-toml/-/smol-toml-1.6.1.tgz", + "integrity": "sha512-dWUG8F5sIIARXih1DTaQAX4SsiTXhInKf1buxdY9DIg4ZYPZK5nGM1VRIYmEbDbsHt7USo99xSLFu5Q1IqTmsg==", "dev": true, "license": "BSD-3-Clause", "engines": { diff --git a/package.json b/package.json index 6a19aecb3bfc28e..0b9ec8db4065cd1 100644 --- a/package.json +++ b/package.json @@ -72,7 +72,7 @@ "imagemin-svgo": "^12.0.0", "is-svg": "^6.1.0", "lefthook": "^2.1.6", - "markdownlint-cli2": "0.22.0", + "markdownlint-cli2": "0.22.1", "markdownlint-rule-search-replace": "1.2.0", "node-html-parser": "^7.1.0", "parse-diff": "^0.12.0",