mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-10-19 00:05:36 +00:00
bug 1471281: geckodriver: update geckodriver build instructions; r=whimboo
This commit is contained in:
Andreas Tolfsen
parent
95641b9fb4
commit
0029ce8495
@ -616,12 +616,6 @@ protocol. geckodriver translates WebDriver [commands], [responses],
|
||||
and [errors] to the [Marionette protocol], and acts as a proxy between
|
||||
[WebDriver] and [Marionette].
|
||||
|
||||
geckodriver is built in the [Firefox CI] by default but _not_ if you
|
||||
build Firefox locally. To enable building of geckodriver locally,
|
||||
ensure you put this in your [mozconfig]:
|
||||
|
||||
ac_add_options --enable-geckodriver
|
||||
|
||||
You build geckodriver with the `./mach build testing/geckodriver`
|
||||
command, run tests with `./mach test testing/geckodriver`, and run
|
||||
the built executable with `./mach geckodriver -- --other --flags`.
|
||||
|
||||
@ -1,26 +1,19 @@
|
||||
Building geckodriver
|
||||
====================
|
||||
|
||||
geckodriver is written in Rust, a systems programming language
|
||||
geckodriver is written in [Rust], a systems programming language
|
||||
from Mozilla. Crucially, it relies on the [webdriver crate] to
|
||||
provide the HTTPD and do most of the heavy lifting of marshalling
|
||||
the WebDriver protocol. geckodriver translates WebDriver [commands],
|
||||
[responses], and [errors] to the [Marionette protocol], and acts
|
||||
as a proxy between [WebDriver] and [Marionette].
|
||||
|
||||
geckodriver is an optional build component when building Firefox,
|
||||
which means it is not built by default when invoking `./mach build`.
|
||||
To enable building of geckodriver, ensure to put this in your [mozconfig]:
|
||||
To build geckodriver:
|
||||
|
||||
ac_add_options --enable-geckodriver
|
||||
% ./mach build testing/geckodriver
|
||||
|
||||
Because we use geckodriver in testing, particularly as part of the
|
||||
Web Platform Tests, it _is_ built by default in the [Firefox CI].
|
||||
A regular `-b do -p all -u none -t none` try syntax will build
|
||||
geckodriver on all the supported platforms. The build will be part
|
||||
of the `B` task.
|
||||
|
||||
If you use artifact builds you may also build geckodriver using cargo:
|
||||
If you use artifact builds you may build geckodriver using cargo,
|
||||
since mach in this case does not have a compile environment:
|
||||
|
||||
% cd testing/geckodriver
|
||||
% cargo build
|
||||
@ -36,14 +29,7 @@ You can run your freshly built geckodriver this way:
|
||||
|
||||
% ./mach geckodriver -- --other --flags
|
||||
|
||||
And run its unit tests like this:
|
||||
|
||||
% ./mach test testing/geckodriver
|
||||
|
||||
Or by invoking cargo in its subdirectory:
|
||||
|
||||
% cd testing/geckodriver
|
||||
% cargo test
|
||||
See <Testing.md> for how to run tests.
|
||||
|
||||
[Rust]: https://www.rust-lang.org/
|
||||
[webdriver crate]: https://crates.io/crates/webdriver
|
||||
@ -53,39 +39,3 @@ Or by invoking cargo in its subdirectory:
|
||||
[Marionette protocol]: /testing/marionette/doc/marionette/Protocol.html
|
||||
[WebDriver]: https://w3c.github.io/webdriver/
|
||||
[Marionette]: /testing/marionette/doc/marionette
|
||||
[mozconfig]: https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Build_Instructions/Configuring_Build_Options
|
||||
[Firefox CI]: https://treeherder.mozilla.org/
|
||||
|
||||
|
||||
Making geckodriver part of the official build
|
||||
---------------------------------------------
|
||||
|
||||
There is a long-term intention to include geckodriver as part of
|
||||
the regular Firefox build.
|
||||
|
||||
When we migrated geckodriver from GitHub into central it was originally
|
||||
enabled by default in all local builds. Since this was one of the
|
||||
very first Rust components to land in central, support for Rust was a
|
||||
little bit experimental and we discovered a couple of different problems:
|
||||
|
||||
(1) Not all developers had Rust installed, and support for Rust
|
||||
in the tree was experimental. This caused some compile
|
||||
errors in particular on Windows, and at the time developers
|
||||
were not happy with requiring Rust for building Firefox.
|
||||
|
||||
(2) The additional build time induced by including a fairly large
|
||||
Rust component in the default build was considered too high.
|
||||
|
||||
At the time of writing, Rust support in central has improved vastly.
|
||||
We also require Rust for regular Firefox builds, which addresses
|
||||
part of issue 1.
|
||||
|
||||
Our working theory is that we now build so much Rust code in central
|
||||
that many of the dependencies geckodriver relies on and that takes
|
||||
up a lot of time to build will have been built as dependencies for
|
||||
other Rust components in the tree, effectively making the additional
|
||||
time it takes to build geckodriver less prominent than it was when
|
||||
we originally tried including it in the default build.
|
||||
|
||||
This work is tracked as part of
|
||||
<https://bugzilla.mozilla.org/show_bug.cgi?id=1471281>.
|
||||
|
||||
57
testing/geckodriver/doc/Testing.md
Normal file
57
testing/geckodriver/doc/Testing.md
Normal file
@ -0,0 +1,57 @@
|
||||
Testing geckodriver
|
||||
===================
|
||||
|
||||
We verify and test geckodriver in a couple of different ways.
|
||||
Since it is an implementation of the WebDriver web standard, we share
|
||||
a set of conformance tests with other browser vendors through the
|
||||
[Web Platform Tests] (WPT) initiative. This lets us ensure web
|
||||
compatibility between _different_ WebDriver implementations for
|
||||
different browsers.
|
||||
|
||||
In addition to the WPT tests, geckodriver and webdriver have
|
||||
unit tests. These are written in Rust, but you must explicitly
|
||||
tell mach to build these by adding the following line to your [mozconfig]:
|
||||
|
||||
ac_add_options --enable-rust-tests
|
||||
|
||||
Tests can then be run like this:
|
||||
|
||||
% ./mach test testing/geckodriver
|
||||
|
||||
To run the more extensive WPT tests you can use mach, but first
|
||||
make sure you have built Firefox:
|
||||
|
||||
% ./mach build
|
||||
% ./mach wpt testing/web-platform/tests/webdriver
|
||||
|
||||
As these are functional integration tests and pop up Firefox windows
|
||||
sporadically, a helpful tip is to surpress the window whilst you
|
||||
are running them by using Firefox’ [headless mode]:
|
||||
|
||||
% MOZ_HEADLESS=1 ./mach wpt testing/web-platform/tests/webdriver
|
||||
|
||||
In addition to the `MOZ_HEADLESS` output variable there is also
|
||||
`MOZ_HEADLESS_WIDTH` and `MOZ_HEADLESS_HEIGHT` to control the
|
||||
dimensions of the no-op virtual display. This is similar to using
|
||||
xvfb(1) which you may know from the X windowing system, but has
|
||||
the additional benefit of also working on macOS and Windows.
|
||||
|
||||
As you get in to development of geckodriver and Marionette you will
|
||||
increasingly grow to understand our love for [trace-level logs].
|
||||
They provide us with the input—the HTTP requests—from the client
|
||||
(in WPT’s case from the tests’ use of a custom WebDriver client),
|
||||
the translation geckodriver makes to the [Marionette protocol],
|
||||
the log output from Marionette, its responses back to geckodriver,
|
||||
and finally the output—or the HTTP response—back to the client.
|
||||
|
||||
The [trace-level logs] can be surfaced by passing on the `-vv`
|
||||
flag to geckodriver through WPT:
|
||||
|
||||
% ./mach wpt --webdriver-arg=-vv testing/web-platform/tests/webdriver
|
||||
|
||||
[Web Platform Tests]: http://web-platform-tests.org/
|
||||
[cargo]: http://doc.crates.io/guide.html
|
||||
[headless mode]: https://developer.mozilla.org/en-US/Firefox/Headless_mode
|
||||
[mozconfig]: https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Build_Instructions/Configuring_Build_Options
|
||||
[trace-level logs]: TraceLogs.html
|
||||
[Marionette protocol]: https://firefox-source-docs.mozilla.org/testing/marionette/marionette/Protocol.html
|
||||
@ -26,4 +26,5 @@ For developers
|
||||
:maxdepth: 1
|
||||
|
||||
Building.md
|
||||
Testing.md
|
||||
Releasing.md
|
||||
|
||||
Loading…
Reference in New Issue
Block a user