Follow the setup instructions for Gerrit backend developers where applicable.
Follow the instructions here to get and install Bazel.
The minimum nodejs version supported is 8.x+
# Debian experimental sudo apt-get install nodejs-legacy sudo apt-get install npm # OS X with Homebrew brew install node brew install npm
All other platforms: download from nodejs.org.
Various steps below require installing additional npm packages. The full list of dependencies can be installed with:
It may complain about a missing
email@example.com peer dependency, which is harmless.
To test the local Polymer frontend against gerrit-review.googlesource.com simply execute:
Then visit http://localhost:8081.
This method is based on a simple hand-written Go webserver. Mostly it just switches between serving files locally and proxying the real server based on the file name. It also does some basic response rewriting, e.g. it patches the
config/server/info response with plugin information provided on the command line:
The biggest draw back of this method is that you cannot log in, so cannot test scenarios that require it.
MITM Proxy is an open source product for proxying https servers. The contrib/mitm-ui/ directory contains scripts (and documentation) for using this technology (instead of the Go server). These scripts are somewhat experimental and unmaintained though.
Set up a local test site once:
For running a locally built Gerrit war against your test instance use this command, and add the
--polygerrit-dev option, if you want to serve the Polymer frontend directly from the sources in
polygerrit_ui/app/ instead of from the war:
$(bazel info output_base)/external/local_jdk/bin/java \ -DsourceRoot=$(bazel info workspace) \ -jar bazel-bin/gerrit.war daemon \ -d $GERRIT_SITE \ --console-log \ --polygerrit-dev
This step requires the
web-component-tester npm module.
Note: it may be necessary to add the options
--unsafe-perm=true --allow-root to the
npm install command to avoid file permission errors.
For daily development you typically only want to run and debug individual tests. Run the local Go proxy server and navigate for example to http://localhost:8081/elements/change/gr-account-entry/gr-account-entry_test.html. Check “Disable cache” in the “Network” tab of Chrome's dev tools, so code changes are picked up on “reload”.
Our CI integration ensures that all tests are run when you upload a change to Gerrit, but you can also run all tests locally in headless mode:
To allow the tests to run in Safari:
To run Chrome tests in headless mode:
WCT_HEADLESS_MODE=1 WCT_ARGS='--verbose -l chrome' ./polygerrit-ui/app/run_test.sh
In addition, we encourage the use of ESLint. It is available as a command line utility, as well as a plugin for most editors and IDEs.
eslint-config-google is a port of the Google JS Style Guide to an ESLint config module, and
eslint-plugin-html allows ESLint to lint scripts inside HTML. We have an .eslintrc.json config file in the polygerrit-ui/ directory configured to enforce the preferred style of the PolyGerrit project. After installing, you can use
eslint on any new file you create. In addition, you can supply the
--fix flag to apply some suggested fixes for simple style issues. If you modify JS inside of
<script> tags, like for test suites, you may have to supply the
--ext .html flag.
Some useful commands:
npm run eslint
node_modules/eslint/bin/eslint.js --ext .html,.js polygerrit-ui/app/$YOUR_DIR_HERE
git diff --name-only master | xargs node_modules/eslint/bin/eslint.js --ext .html,.js
We also use the
polylint tool to lint use of Polymer. To install polylint, execute the following command.
To run polylint, execute the following command.
bazel test //polygerrit-ui/app:polylint_test
npm run polylint
Polymer elements are not type checked against the element definition, making it trivial to break the display when refactoring or moving code. We now run additional tests to help ensure that template types are checked.
A few notes to ensure that these tests pass
These tests require the
fried-twinkie npm packages.
To run on all files, execute the following command:
npm run test-template
To run on a specific top level directory (ex: change-list)
TEMPLATE_NO_DEFAULT=true ./polygerrit-ui/app/run_template_test.sh //polygerrit-ui/app:template_test_change-list
To run on a specific file (ex: gr-change-list-view), execute the following command:
TEMPLATE_NO_DEFAULT=true ./polygerrit-ui/app/run_template_test.sh //polygerrit-ui/app:template_test_<TOP_LEVEL_DIRECTORY> --test_arg=<VIEW_NAME>
TEMPLATE_NO_DEFAULT=true ./polygerrit-ui/app/run_template_test.sh //polygerrit-ui/app:template_test_change-list --test_arg=gr-change-list-view