diff options
Diffstat (limited to 'testing/web-platform/tests/docs/writing-tests/lint-tool.md')
-rw-r--r-- | testing/web-platform/tests/docs/writing-tests/lint-tool.md | 78 |
1 files changed, 78 insertions, 0 deletions
diff --git a/testing/web-platform/tests/docs/writing-tests/lint-tool.md b/testing/web-platform/tests/docs/writing-tests/lint-tool.md new file mode 100644 index 0000000000..95f8b57415 --- /dev/null +++ b/testing/web-platform/tests/docs/writing-tests/lint-tool.md @@ -0,0 +1,78 @@ +# Lint Tool + +We have a lint tool for catching common mistakes in test files. You can run +it manually by running the `wpt lint` command from the root of your local +web-platform-tests working directory like this: + +``` +./wpt lint +``` + +The lint tool is also run automatically for every submitted pull request, +and reviewers will not merge branches with tests that have lint errors, so +you must either [fix all lint errors](#fixing-lint-errors), or you must +[add an exception](#updating-the-ignored-files) to suppress the errors. + +## Fixing lint errors + +You must fix any errors the lint tool reports, unless an error is for something +essential to a certain test or that for some other exceptional reason shouldn't +prevent the test from being merged; in those cases you can [add an +exception](#updating-the-ignored-files) to suppress the errors. In all other +cases, follow the instructions below to fix all errors reported. + +<!-- + This listing is automatically generated from the linting tool's Python source + code. +--> + +```eval_rst +.. wpt-lint-rules:: tools.lint.rules +``` + +## Updating the ignored files + +Normally you must [fix all lint errors](#fixing-lint-errors). But in the +unusual case of error reports for things essential to certain tests or that +for other exceptional reasons shouldn't prevent a merge of a test, you can +update and commit the `lint.ignore` file in the web-platform-tests root +directory to suppress errors the lint tool would report for a test file. + +To add a test file or directory to the list, use the following format: + +``` +ERROR TYPE:file/name/pattern +``` + +For example, to ignore all `TRAILING WHITESPACE` errors in the file +`example/file.html`, add the following line to the `lint.ignore` file: + +``` +TRAILING WHITESPACE:example/file.html +``` + +To ignore errors for an entire directory rather than just one file, use the `*` +wildcard. For example, to ignore all `TRAILING WHITESPACE` errors in the +`example` directory, add the following line to the `lint.ignore` file: + +``` +TRAILING WHITESPACE:example/* +``` + +Similarly, you can also +use +[shell-style wildcards](https://docs.python.org/library/fnmatch.html) to +express other filename patterns or directory-name patterns. + +Finally, to ignore just one line in a file, use the following format: + +``` +ERROR TYPE:file/name/pattern:line_number +``` + +For example, to ignore the `TRAILING WHITESPACE` error for just line 128 of the +file `example/file.html`, add the following to the `lint.ignore` file: + +``` +TRAILING WHITESPACE:example/file.html:128 +``` |