Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add docs for servodriver. #59

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Add docs for servodriver. #59

wants to merge 3 commits into from

Conversation

jdm
Copy link
Member

@jdm jdm commented Mar 2, 2025

No description provided.

@jdm
Add docs for servodriver.
c66b592 
Signed-off-by: Josh Matthews <josh@joshmatthews.net>
@delan
Copy link
Member

delan commented Mar 3, 2025

I will review this on Wednesday :)

@delan
Copy link
Member

delan commented Mar 6, 2025

Sorry for the delay, I will try to review this tomorrow.

delan
delan requested changes Mar 10, 2025
View reviewed changes
Copy link
Member

@delan delan left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks! These are very useful docs, and my comments are mostly very minor.

src/architecture/servodriver.md
# The Servodriver test harness

Servodriver is a test harness built on top of the wptrunner framework and a WebDriver server. It is not yet enabled by default, but can be run with the `--product servodriver` argument appended to any `test-wpt` command.
Servodriver is made of three main components—the web server inside Servo that implements the [WebDriver specification](https://www.w3.org/TR/webdriver2/), the python test harness that orchestrates the browser, and the scripts that are loaded inside the test pages.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Servodriver is made of three main components—the web server inside Servo that implements the [WebDriver specification](https://www.w3.org/TR/webdriver2/), the python test harness that orchestrates the browser, and the scripts that are loaded inside the test pages.
Servodriver is made of three main components: the web server inside Servo that implements the [WebDriver specification](https://www.w3.org/TR/webdriver2/), the Python test harness that orchestrates the browser, and the scripts that are loaded inside the test pages.

this is a list, so we can be more specific and use a colon. also, consider reordering this list to match the order of the sections below or vice versa?

src/architecture/servodriver.md

## Servo’s webdriver implementation

There are three main components to this implementation—the server handler, the script handler, and the input handler.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
There are three main components to this implementation—the server handler, the script handler, and the input handler.
There are three main components to this implementation: the server handler, the script handler, and the input handler.

src/architecture/servodriver.md
Our Servodriver executor delegates a lot of logic to the common [WebDriverTestharnessExecutor](https://github.com/servo/servo/blob/3421185737deefe27e51e104708b02d9b3d4f4f3/tests/wpt/tests/tools/wptrunner/wptrunner/executors/executorwebdriver.py#L948). This executor is responsible for executing scripts that ensure that the [testdriver harness executes](https://github.com/servo/servo/blob/3421185737deefe27e51e104708b02d9b3d4f4f3/tests/wpt/tests/tools/wptrunner/wptrunner/executors/executorwebdriver.py#L840) and that the python harness is able to retrieve test results from the browser.


## Servo’s webdriver implementation
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
## Servo’s webdriver implementation
## Servo’s WebDriver implementation

src/architecture/servodriver.md

When a webdriver message is received that targets a specific browsing context, it is [handled](https://github.com/servo/servo/blob/3421185737deefe27e51e104708b02d9b3d4f4f3/components/script/script_thread.rs#L2076) by the ScriptThread that contains that document. The logic for processing each command lives in [webdriver_handlers.rs](https://github.com/servo/servo/blob/main/components/script/webdriver_handlers.rs). Any command that returns a value derived from web content must [serialize JS values](https://github.com/servo/servo/blob/3421185737deefe27e51e104708b02d9b3d4f4f3/components/script/webdriver_handlers.rs#L162) as values that the webdriver server can convert into [API value types](https://doc.servo.org/serde_json/value/enum.Value.html).

We expose [two web-accessible methods](https://github.com/servo/servo/blob/3421185737deefe27e51e104708b02d9b3d4f4f3/components/script/dom/window.rs#L1189-L1203) for communicating async results to the webdriver server, `Window.webdriverCallback` and `Window.webdriverTimeout`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
We expose [two web-accessible methods](https://github.com/servo/servo/blob/3421185737deefe27e51e104708b02d9b3d4f4f3/components/script/dom/window.rs#L1189-L1203) for communicating async results to the webdriver server, `Window.webdriverCallback` and `Window.webdriverTimeout`.
We expose [two web-accessible methods](https://github.com/servo/servo/blob/3421185737deefe27e51e104708b02d9b3d4f4f3/components/script/dom/window.rs#L1189-L1203) for communicating async results to the WebDriver server: `Window.webdriverCallback` and `Window.webdriverTimeout`.

src/architecture/servodriver.md
## The wptrunner harness

Wptrunner is the harness that uses an `executor` and `browser` combination to launch a supported product.
The [browser](https://github.com/servo/servo/blob/3421185737deefe27e51e104708b02d9b3d4f4f3/tests/wpt/tests/tools/wptrunner/wptrunner/browsers/servodriver.py) defines python classes to instantiate and methods to invoke for supported configurations, as well as arguments to pass to the Servo binary when launching it.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The [browser](https://github.com/servo/servo/blob/3421185737deefe27e51e104708b02d9b3d4f4f3/tests/wpt/tests/tools/wptrunner/wptrunner/browsers/servodriver.py) defines python classes to instantiate and methods to invoke for supported configurations, as well as arguments to pass to the Servo binary when launching it.
The [browser](https://github.com/servo/servo/blob/main/tests/wpt/tests/tools/wptrunner/wptrunner/browsers/servodriver.py) defines Python classes to instantiate and methods to invoke for supported configurations, as well as arguments to pass to the Servo binary when launching it.

src/architecture/servodriver.md
## The test page scripts

The testdriver harness works by incorporating all of these elements together.
The executor [opens a new window](https://github.com/servo/servo/blob/3421185737deefe27e51e104708b02d9b3d4f4f3/tests/wpt/tests/tools/wptrunner/wptrunner/executors/executorwebdriver.py#L850) and invokes an async script that [sets up a testdriver callback](https://github.com/servo/servo/blob/3421185737deefe27e51e104708b02d9b3d4f4f3/tests/wpt/tests/tools/wptrunner/wptrunner/executors/testharness_webdriver_resume.js) (which is `Window.webdriverCallback`).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The executor [opens a new window](https://github.com/servo/servo/blob/3421185737deefe27e51e104708b02d9b3d4f4f3/tests/wpt/tests/tools/wptrunner/wptrunner/executors/executorwebdriver.py#L850) and invokes an async script that [sets up a testdriver callback](https://github.com/servo/servo/blob/3421185737deefe27e51e104708b02d9b3d4f4f3/tests/wpt/tests/tools/wptrunner/wptrunner/executors/testharness_webdriver_resume.js) (which is `Window.webdriverCallback`).
The executor [opens a new window](https://github.com/servo/servo/blob/3421185737deefe27e51e104708b02d9b3d4f4f3/tests/wpt/tests/tools/wptrunner/wptrunner/executors/executorwebdriver.py#L850) and invokes an async script that [sets the testdriver callback](https://github.com/servo/servo/blob/3421185737deefe27e51e104708b02d9b3d4f4f3/tests/wpt/tests/tools/wptrunner/wptrunner/executors/testharness_webdriver_resume.js) to `Window.webdriverCallback` (`arguments[arguments.length - 1]`).

src/architecture/servodriver.md

The testdriver harness works by incorporating all of these elements together.
The executor [opens a new window](https://github.com/servo/servo/blob/3421185737deefe27e51e104708b02d9b3d4f4f3/tests/wpt/tests/tools/wptrunner/wptrunner/executors/executorwebdriver.py#L850) and invokes an async script that [sets up a testdriver callback](https://github.com/servo/servo/blob/3421185737deefe27e51e104708b02d9b3d4f4f3/tests/wpt/tests/tools/wptrunner/wptrunner/executors/testharness_webdriver_resume.js) (which is `Window.webdriverCallback`).
This window creates [a message queue](https://github.com/servo/servo/blob/3421185737deefe27e51e104708b02d9b3d4f4f3/tests/wpt/tests/tools/wptrunner/wptrunner/executors/message-queue.js#L30) which is [read by the executor harness](https://github.com/servo/servo/blob/3421185737deefe27e51e104708b02d9b3d4f4f3/tests/wpt/tests/tools/wptrunner/wptrunner/executors/executorwebdriver.py#L904-L905).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
This window creates [a message queue](https://github.com/servo/servo/blob/3421185737deefe27e51e104708b02d9b3d4f4f3/tests/wpt/tests/tools/wptrunner/wptrunner/executors/message-queue.js#L30) which is [read by the executor harness](https://github.com/servo/servo/blob/3421185737deefe27e51e104708b02d9b3d4f4f3/tests/wpt/tests/tools/wptrunner/wptrunner/executors/executorwebdriver.py#L904-L905).
This window creates [a message queue](https://github.com/servo/servo/blob/3421185737deefe27e51e104708b02d9b3d4f4f3/tests/wpt/tests/tools/wptrunner/wptrunner/executors/message-queue.js#L30), which is [read by the executor harness](https://github.com/servo/servo/blob/3421185737deefe27e51e104708b02d9b3d4f4f3/tests/wpt/tests/tools/wptrunner/wptrunner/executors/executorwebdriver.py#L904-L905).

src/architecture/servodriver.md
The testdriver harness works by incorporating all of these elements together.
The executor [opens a new window](https://github.com/servo/servo/blob/3421185737deefe27e51e104708b02d9b3d4f4f3/tests/wpt/tests/tools/wptrunner/wptrunner/executors/executorwebdriver.py#L850) and invokes an async script that [sets up a testdriver callback](https://github.com/servo/servo/blob/3421185737deefe27e51e104708b02d9b3d4f4f3/tests/wpt/tests/tools/wptrunner/wptrunner/executors/testharness_webdriver_resume.js) (which is `Window.webdriverCallback`).
This window creates [a message queue](https://github.com/servo/servo/blob/3421185737deefe27e51e104708b02d9b3d4f4f3/tests/wpt/tests/tools/wptrunner/wptrunner/executors/message-queue.js#L30) which is [read by the executor harness](https://github.com/servo/servo/blob/3421185737deefe27e51e104708b02d9b3d4f4f3/tests/wpt/tests/tools/wptrunner/wptrunner/executors/executorwebdriver.py#L904-L905).
Subsequently, each test that runs is opened as a new window—this allows them to use `opener.postMessage` to communicate with the original window, which allows the testdriver APIs to send messages that [represent webdriver API calls](https://github.com/servo/servo/blob/3421185737deefe27e51e104708b02d9b3d4f4f3/tests/wpt/tests/tools/wptrunner/wptrunner/testdriver-extra.js#L286-L296).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Subsequently, each test that runs is opened as a new window—this allows them to use `opener.postMessage` to communicate with the original window, which allows the testdriver APIs to send messages that [represent webdriver API calls](https://github.com/servo/servo/blob/3421185737deefe27e51e104708b02d9b3d4f4f3/tests/wpt/tests/tools/wptrunner/wptrunner/testdriver-extra.js#L286-L296).
Subsequently, each test that runs is opened as a new window; these windows can then use `opener.postMessage` to communicate with the original window, which allows the testdriver APIs to send messages that [represent WebDriver API calls](https://github.com/servo/servo/blob/3421185737deefe27e51e104708b02d9b3d4f4f3/tests/wpt/tests/tools/wptrunner/wptrunner/testdriver-extra.js#L286-L296).

src/architecture/servodriver.md
RUST_LOG=webdriver_server,webdriver,script::webdriver_handlers,constellation
```

This usually makes clear if the expected API calls are being processed.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
This usually makes clear if the expected API calls are being processed.
This usually makes it clear if the expected API calls are being processed.

src/architecture/servodriver.md

This usually makes clear if the expected API calls are being processed.

When debugging input-related problems, add JS debugging lines that log the `getBoundingClientRect()` of whatever element is being clicked, then compare the coordinates received by the compositor when clicking manually vs. the coordinates received from the webdriver server.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
When debugging input-related problems, add JS debugging lines that log the `getBoundingClientRect()` of whatever element is being clicked, then compare the coordinates received by the compositor when clicking manually vs. the coordinates received from the webdriver server.
When debugging input-related problems, add JS debugging lines that log the `getBoundingClientRect()` of whatever element is being clicked, then compare the coordinates received by the compositor when clicking manually vs the coordinates received from the WebDriver server.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@delan delan delan requested changes

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
2 participants
@jdm @delan