Blame - docs/testing/local_prototyping_guide.md - chromium/src

blob: 51dbbced8b4aef4bcd4519e53e9c5aa6e999c93a [file] [log] [blame] [view]

Maksim Sadym	c14c9a64	2025-07-11 10:37:05	[diff] [blame]	1	# Local Prototyping and Testing Chromium Web Platform Features with Web Platform Tests
				2
Maksim Sadym	60c68339	2025-07-14 15:47:50	[diff] [blame]	3	This document can be useful if you want to create a local prototype of a new
				4	web feature and test it using WPT before proposing any changes in WebDriver BiDi
				5	or in Chromium.
				6
Maksim Sadym	5419648	2025-07-11 09:35:51	[diff] [blame]	7	This guide details the process of configuring your local development environment
				8	for prototyping and testing new web features. It covers the entire workflow for
				9	Chromium browsers, from initial ideation and implementing Chromium DevTools
Maksim Sadym	60c68339	2025-07-14 15:47:50	[diff] [blame]	10	Protocol (CDP) methods to creating and running Web Platform Tests (WPT).
				11
				12	The following aspects are covered:
Maksim Sadym	5419648	2025-07-11 09:35:51	[diff] [blame]	13	1. Chrome Devtools Protocol (CDP)
				14	1. WebDriver BiDi CDDL
				15	1. Chromium BiDi
				16	1. WPT
				17
				18	[TOC]
				19
				20	## CDP
Maksim Sadym	c14c9a64	2025-07-11 10:37:05	[diff] [blame]	21	If the required functionality is not yet supported by CDP, begin by implementing
				22	it yourself. Clone the Chromium repository to your machine and add your new
Maksim Sadym	5419648	2025-07-11 09:35:51	[diff] [blame]	23	methods and events to CDP.
Maksim Sadym	c14c9a64	2025-07-11 10:37:05	[diff] [blame]	24	[Refer to this doc guidance](https://source.chromium.org/chromium/chromium/src/+/main:third_party/blink/public/devtools_protocol/README.md).
Maksim Sadym	5419648	2025-07-11 09:35:51	[diff] [blame]	25
Maksim Sadym	c14c9a64	2025-07-11 10:37:05	[diff] [blame]	26	**Don't forget to add [inspector protocol tests](https://source.chromium.org/chromium/chromium/src/+/main:third_party/blink/web_tests/http/tests/inspector-protocol/)
				27	to ensure everything works as expected!**
				28	Refer to [this example CL](https://crrev.com/c/6578504).
Maksim Sadym	5419648	2025-07-11 09:35:51	[diff] [blame]	29
Maksim Sadym	c14c9a64	2025-07-11 10:37:05	[diff] [blame]	30	### Build Chromium
Maksim Sadym	5419648	2025-07-11 09:35:51	[diff] [blame]	31	You will need the following targets to be build:
				32	```shell
				33	autoninja -C out/Default chrome chromedriver headless_shell
				34	```
				35	Let’s assume the build artefacts have paths `${LOCAL_BROWSER_BIN}`,
				36	`${LOCAL_HEADLESS_SHELL_BIN}` and `${LOCAL_CHROMEDRIVER_BIN}`.
				37
				38	## WebDriver BiDi CDDL
				39	WebDriver BiDi uses [CDDL](https://datatracker.ietf.org/doc/html/rfc8610) to
Maksim Sadym	60c68339	2025-07-14 15:47:50	[diff] [blame]	40	declare the types for commands and events. To prototype changes to the WebDriver
				41	BiDi protocol's CDDL before they are merged into the main repository, follow
				42	these steps.
				43
				44	### Clone repository
				45	Clone the
Maksim Sadym	5419648	2025-07-11 09:35:51	[diff] [blame]	46	[WebDriver BiDi repository](https://github.com/w3c/webdriver-bidi), add the new
Maksim Sadym	c14c9a64	2025-07-11 10:37:05	[diff] [blame]	47	methods and events to the CDDL schemas. The specification text can be omitted at
Maksim Sadym	5419648	2025-07-11 09:35:51	[diff] [blame]	48	this prototyping stage. You can refer to the
				49	[emulation.setLocaleOverride](https://github.com/w3c/webdriver-bidi/blob/a8b68a1e3468ffa90502d2507444b9b1d394b287/index.bs#L5810)
				50	command and to the
				51	[browsingContext.ContextCreated](https://github.com/w3c/webdriver-bidi/blob/a8b68a1e3468ffa90502d2507444b9b1d394b287/index.bs#L3092)
				52	event. The important part here is to add the proper CDDL.
				53
				54	### Verify the change
				55	Verify the change in the spec is correct by running this command:
				56	```shell
				57	sh scripts/test.sh
				58	sh scripts/build.sh
				59	```
				60
				61	### Generate CDDL
				62	Generate the CDDL by running this command:
				63	```shell
				64	scripts/cddl/generate.js
				65	```
				66	This will create a file `all.cddl`. Let its path be `${LOCAL_CDDL}`.
				67
Maksim Sadym	c14c9a64	2025-07-11 10:37:05	[diff] [blame]	68	### External Specifications
Maksim Sadym	60c68339	2025-07-14 15:47:50	[diff] [blame]	69	If the changes are done in an existing external spec, for example
				70	[Permissions](https://www.w3.org/TR/permissions/) or
				71	[Web Bluetooth](https://webbluetoothcg.github.io/web-bluetooth/), the CDDL
				72	should be generated differently. For example, for changes in "Web Bluetooth":
				73	1. Checkout [`web-bluetooth`](https://webbluetoothcg.github.io/web-bluetooth/)
				74	spec locally.
				75	1. Enter the `web-bluetooth` spec directory.
				76	1. Run providing the proper path to the `webdriver-bidi` spec folder.
				77	```sh
				78	../webdriver-bidi/scripts/cddl/generate.js ./index.bs
				79	mv all.cddl bluetooth.cddl
				80	```
				81	This will generate `bluetooth.cddl` in the `web-bluetooth` folder. Let its path
				82	be `${LOCAL_CDDL}`.
Maksim Sadym	5419648	2025-07-11 09:35:51	[diff] [blame]	83
				84	## Chromium BiDi
				85	[Chromium BiDi](https://github.com/GoogleChromeLabs/chromium-bidi) is an
				86	implementation of the WebDriver BiDi protocol for Chromium.
				87
Maksim Sadym	c14c9a64	2025-07-11 10:37:05	[diff] [blame]	88	### Regenerate BiDi types
Maksim Sadym	5419648	2025-07-11 09:35:51	[diff] [blame]	89	The TypeScript types and zod schemes are generated based on the WebDriver BiDi
				90	CDDL.
				91	```shell
				92	node tools/generate-bidi-types.mjs --cddl-file ${LOCAL_CDDL}
				93	npm run format
				94	```
				95
				96	### Fix the build
				97	If a new BiDi command is added, add it to the
				98	[`CommandProcessor`](https://github.com/GoogleChromeLabs/chromium-bidi/blob/de72d10875fb77c6908cb116bb46a6b3d49491b7/src/bidiMapper/CommandProcessor.ts#L163).
				99	Verify the build works:
				100	```shell
				101	npm run build
				102	```
				103
				104	### Implement BiDi command parameters parsing
Maksim Sadym	c14c9a64	2025-07-11 10:37:05	[diff] [blame]	105	This is another manual step requiring implementation effort. You can refer to
				106	[this example pull request](https://github.com/GoogleChromeLabs/chromium-bidi/pull/3544) as an
Maksim Sadym	5419648	2025-07-11 09:35:51	[diff] [blame]	107	example.
				108
				109	### Implement the command and event
				110	Now, implement the logic for your new BiDi command or event. This means calling
				111	the new CDP methods or listening for events you added earlier. Since the
				112	TypeScript types for CDP in "Chromium BiDi" aren't automatically updated with
Maksim Sadym	c14c9a64	2025-07-11 10:37:05	[diff] [blame]	113	your local changes, you'll encounter TypeScript errors. As a temporary workaround
				114	for prototyping, you'll need to cast your new CDP calls or event handlers to
				115	`any` to allow compilation.
Maksim Sadym	5419648	2025-07-11 09:35:51	[diff] [blame]	116
				117	### Add e2e tests
Maksim Sadym	c14c9a64	2025-07-11 10:37:05	[diff] [blame]	118	Add [e2e tests](https://github.com/GoogleChromeLabs/chromium-bidi?tab=readme-ov-file#e2e-tests) verifying the new BiDi command works as expected. This is expected to fail with
Maksim Sadym	5419648	2025-07-11 09:35:51	[diff] [blame]	119	the Canary Chromium, as the required CDP changes are not present there, so you
				120	will need to point the tests to your local Chromium built by the `BROWSER_BIN`
				121	and `LOCAL_CHROMEDRIVER_BIN` environment variables. Test it in headless shell,
				122	headless and headful modes:
				123	```shell
				124	BROWSER_BIN=${LOCAL_HEADLESS_SHELL_BIN} CHROMEDRIVER_BIN=${LOCAL_CHROMEDRIVER_BIN} HEADLESS=old CHROMEDRIVER=true \
				125	npm run e2e -- ${YOUR_TEST_PATH}
				126
				127	BROWSER_BIN=${LOCAL_BROWSER_BIN} CHROMEDRIVER_BIN=${LOCAL_CHROMEDRIVER_BIN} HEADLESS=true CHROMEDRIVER=true \
				128	npm run e2e -- ${YOUR_TEST_PATH}
				129
				130	BROWSER_BIN=${LOCAL_BROWSER_BIN} CHROMEDRIVER_BIN=${LOCAL_CHROMEDRIVER_BIN} HEADLESS=false CHROMEDRIVER=true \
				131	npm run e2e -- ${YOUR_TEST_PATH}
				132	```
				133
				134	### Build Chromium BiDi
Maksim Sadym	c14c9a64	2025-07-11 10:37:05	[diff] [blame]	135	Build again. The path to the built Chromium BiDi script `lib/iife/mapperTab.js`
				136	will be `${LOCAL_MAPPER_TAB_PATH}`.
Maksim Sadym	5419648	2025-07-11 09:35:51	[diff] [blame]	137	```shell
				138	npm run build
				139	```
				140
				141	## WPT
Maksim Sadym	c14c9a64	2025-07-11 10:37:05	[diff] [blame]	142	After the previous steps are complete, you can add the required WPT tests and endpoints. To run WPT tests with the locally built browser, use the following command in the WPT root directory:
Maksim Sadym	5419648	2025-07-11 09:35:51	[diff] [blame]	143	```shell
				144	./wpt run --manifest MANIFEST.json --no-manifest-download \
				145	--binary ${LOCAL_BROWSER_BIN} \
				146	--webdriver-binary ${LOCAL_CHROMEDRIVER_BIN} \
				147	--webdriver-arg=--bidi-mapper-path=${LOCAL_MAPPER_TAB_PATH} \
				148	chrome \
				149	infrastructure/testdriver/bidi/emulation/set_locale_override.https.html
				150	```
				151	Refer to [this documentation](https://docs.google.com/document/d/1uQmNMUzznAH_JvJOTllpL2qNhOEzClTkmZliTnlsNIs/edit?tab=t.0#bookmark=id.lh4ijkuvdxhf)
				152	for instructions on how to add the new commands or events to WPT’s
				153	testdriver.js.