Let libraries trace and record adopted contexts the way New Context does

[d-biehl]

Follow-up to #5318, as discussed there.

With #5318, Browser starts tracing an adopted context, but a library still has to work out the trace path, the video folder and size and the HAR path itself, and register the context for the keyword groups in the trace and for the video in the log. The Electron library did that through internals of PlaywrightState, such as _resolve_trace_file, _set_video_path and _embed_video. This PR gives libraries built on Browser two public methods for it, so that an adopted context follows Browser's settings in the same style as New Context.

• Browser.adopted_context_options(tracing=None, recordVideo=None, recordHar=None) returns an AdoptedContextOptions, a typed dictionary with tracing, recordVideo and recordHar, None when off. They follow the rules of New Context: tracing=True and ROBOT_FRAMEWORK_BROWSER_TRACING give Browser's trace folder, a video gets Browser's video folder and 1280x720 by default, and relative paths are resolved as for New Context. The keys are named like the options, so a library can pass them on to its extension function as keyword arguments.
• Browser.register_adopted_context(context_id, options, video_path=None) registers the adopted context afterwards: the keyword calls become groups in the trace, and the log embeds the video. It returns the video path, or an empty string without a video.

A library in Python then does:

options = self.adopted_context_options(tracing=tracing, recordVideo=record_video, recordHar=record_har)
adopted = self.call_js_keyword("launchElectronApplication", executablePath=path, defaultTimeout=int(self.timeout), **options)
self.register_adopted_context(adopted["contextId"], options, adopted.get("videoPath"))

Two related changes:

• Relative recordHar paths: New Context and New Persistent Context passed the path of recordHar to the Node process as given, so a relative path put the HAR file into the wrapper folder of the installed package. A relative path is now relative to the output directory, as a .zip path of tracing is, and adopted_context_options uses the same rule. Unlike recordVideo and tracing, recordHar has no default location yet. Browser could give it one, for example browser/har/<unique name>.har when the path is left out, and adopted contexts would get it through adopted_context_options too. I left that out to keep this PR small, but I can add it here or in a separate PR if you like the idea.
• Shorter jsextension help: with Let libraries built on Browser hand over their own BrowserContext #5318, the description of the jsextension import argument had grown into a full reference of adoptContext and its options. That is too much detail for an import argument, so it now describes adoptContext in one sentence and links to the website. The details are on the JavaScript extensions page instead, including the two methods above, updated in Document adoptContext for JavaScript extensions robotframework-browser.org#21.

Tests:

• utest/test_adopted_context.py: the options follow New Context, including the global tracing setting, the video defaults and HAR paths. Registering adds the trace groups and embeds the video, and a video path without recordVideo is ignored.
• atest/test/01_Browser_Management/record_har.robot: a relative HAR path ends up in the output directory.

There are no Node or protocol changes. I verified it locally with inv lint, the Python unit tests, and the acceptance test suites Record Har and Adopt Context (inv atest-robot --suite …), with Chromium only. The Electron library uses the two methods instead of Browser's internals, and its tests pass against this branch.

AI / tooling disclosure
This contribution was prepared with assistance from Claude Code (Anthropic). I reviewed the result manually, understand the changes, verified them locally, and confirm that I have the right to submit this contribution under the project license.

[Copilot]

🟡 Changes recommended

Adopted HAR options can forward string booleans to Playwright without conversion.

1 open finding

• Normalize recordHar string values to booleans before Playwright · New

What changed in this PR

Adds public helpers for libraries adopting Browser contexts while aligning tracing, video, and HAR behavior with New Context.

Changes:

• Adds adopted-context option generation and registration.
• Resolves relative HAR paths against the output directory.
• Adds unit and acceptance coverage.

File	Description
Browser/​browser.py	Adds adopted-context APIs and shortens extension help.
Browser/​keywords/​playwright_state.py	Resolves relative HAR paths.
Browser/​utils/​data_types.py	Defines adopted-context option types.
Browser/​utils/​__init__.py	Exports the new type.
utest/​test_adopted_context.py	Tests options and registration.
atest/​test/​01_Browser_Management/​record_har.robot	Verifies relative HAR paths.

🧠 Review effort: Balanced