1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
|
# PolyGerrit
## Installing [Node.js](https://nodejs.org/en/download/)
The minimum nodejs version supported is 6.x+
```sh
# Debian experimental
sudo apt-get install nodejs-legacy
# OS X with Homebrew
brew install node
```
All other platforms: [download from
nodejs.org](https://nodejs.org/en/download/).
## Installing [Bazel](https://bazel.build/)
Follow the instructions
[here](https://gerrit-review.googlesource.com/Documentation/dev-bazel.html#_installation)
to get and install Bazel.
## Local UI, Production Data
This is a quick and easy way to test your local changes against real data.
Unfortunately, you can't sign in, so testing certain features will require
you to use the "test data" technique described below.
### Installing [go](https://golang.org/)
This is required for running the `run-server.sh` script below.
```sh
# Debian/Ubuntu
sudo apt-get install golang
# OS X with Homebrew
brew install go
```
All other platforms: [download from golang.org](https://golang.org/)
Then add go to your path:
```
PATH=$PATH:/usr/local/go/bin
```
### Running the server
To test the local UI against gerrit-review.googlesource.com:
```sh
./run-server.sh
```
Then visit http://localhost:8081
## Local UI, Test Data
One-time setup:
1. [Build Gerrit](https://gerrit-review.googlesource.com/Documentation/dev-bazel.html#_gerrit_development_war_file)
2. Set up a local test site. Docs
[here](https://gerrit-review.googlesource.com/Documentation/linux-quickstart.html) and
[here](https://gerrit-review.googlesource.com/Documentation/dev-readme.html#init).
When your project is set up and works using the classic UI, run a test server
that serves PolyGerrit:
```sh
bazel build polygerrit &&
$(bazel info output_base)/external/local_jdk/bin/java \
-jar bazel-bin/polygerrit.war daemon --polygerrit-dev \
-d ../gerrit_testsite --console-log --show-stack-trace
```
## Running Tests
One-time setup:
```sh
# Debian/Ubuntu
sudo apt-get install npm
# OS X with Homebrew
brew install npm
# All platforms (including those above)
sudo npm install -g web-component-tester
```
Note: it may be necessary to add the options `--unsafe-perm=true --allow-root`
to the `npm install` command to avoid file permission errors.
Run all web tests:
```sh
./polygerrit-ui/app/run_test.sh
```
To allow the tests to run in Safari:
* In the Advanced preferences tab, check "Show Develop menu in menu bar".
* In the Develop menu, enable the "Allow Remote Automation" option.
If you need to pass additional arguments to `wct`:
```sh
WCT_ARGS='-p --some-flag="foo bar"' ./polygerrit-ui/app/run_test.sh
```
For interactively working on a single test file, do the following:
```sh
./polygerrit-ui/run-server.sh
```
Then visit http://localhost:8081/elements/foo/bar_test.html
To run Chrome tests in headless mode:
```sh
WCT_HEADLESS_MODE=1 ./polygerrit-ui/app/run_test.sh
```
Toolchain requirements for headless mode:
* Chrome: 59+
* web-component-tester: v6.5.0+
## Style guide
We follow the [Google JavaScript Style Guide](https://google.github.io/styleguide/javascriptguide.xml)
with a few exceptions. When in doubt, remain consistent with the code around you.
In addition, we encourage the use of [ESLint](http://eslint.org/).
It is available as a command line utility, as well as a plugin for most editors
and IDEs. It, along with a few dependencies, can also be installed through NPM:
```sh
sudo npm install -g eslint eslint-config-google eslint-plugin-html
```
`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:
* To run ESLint on the whole app, less some dependency code:
`eslint --ignore-pattern 'bower_components/' --ignore-pattern 'gr-linked-text' --ignore-pattern 'scripts/vendor' --ext .html,.js polygerrit-ui/app`
* To run ESLint on just the subdirectory you modified:
`eslint --ext .html,.js polygerrit-ui/app/$YOUR_DIR_HERE`
* To run the linter on all of your local changes:
`git diff --name-only master | xargs eslint --ext .html,.js`
We also use the polylint tool to lint use of Polymer. To install polylint,
execute the following command.
```sh
npm install -g polylint
```
To run polylint, execute the following command.
```sh
bazel test //polygerrit-ui/app:polylint_test
```
## Template Type Safety
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
- Any functions with optional parameters will need closure annotations.
- Any Polymer parameters that are nullable or can be multiple types (other than the one explicitly delared) will need type annotations.
A few dependencies are necessary to run these tests:
``` sh
npm install -g typescript fried-twinkie
```
To run on all files, execute the following command:
```sh
bazel test //polygerrit-ui/app:all --test_tag_filters=template --test_output errors
```
To run on a specific top level directory (ex: change-list)
```sh
bazel test //polygerrit-ui/app:template_test_change-list --test_output errors
```
To run on a specific file (ex: gr-change-list-view), execute the following command:
```sh
bazel test //polygerrit-ui/app:template_test_<TOP_LEVEL_DIRECTORY> --test_arg=<VIEW_NAME> --test_output errors
```
```sh
bazel test //polygerrit-ui/app:template_test_change-list --test_arg=gr-change-list-view --test_output errors
```
|
