Gathering information about test filter files into a README.md file.

testing/buildbot/filters/README.md

Index: testing/buildbot/filters/README.md
diff --git a/testing/buildbot/filters/README.md b/testing/buildbot/filters/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..7523dba40dd77fd4534d26d128541a5a858f6434
--- /dev/null
+++ b/testing/buildbot/filters/README.md
@@ -0,0 +1,114 @@
+# Test filter files
+
+## Summary
+
+This directory contains files that list tests that are not yet ready to run in a
+particular mode. For example - the `site-per-process.browser_tests.filter` file
+lists tests that should be excluded when running `browser_tests` in
+`--site-per-process` mode.
+
+## File syntax
+
+Contents of test filter files follow the syntax below:
+
+-   Empty lines are ignored
+-   Lines starting with the '#' character are treated as comments and ignored.
+-   All other lines specify a single [test name pattern][gtest_filter].
+    -   Patterns prefixed with the '-' character specify tests to exclude from a
+        test run.
+    -   All other patterns specify tests to include in a test run.

[alexmos, 2016/11/03 21:30:58]

nit: while we're at it, should we also warn about what happens if both are
specified? (I.e., that if any positive patterns are specified, the negative
patterns only apply to that set and not the full set of tests, which is probably
not what you want?)

[Łukasz Anforowicz, 2016/11/03 22:00:15]

Done.  Sort of (no warning, just copying the short explanation from gtest docs; 
for good measure I did include the link to the controversal gtest_filter VS
test-launcher-filter-file bug).

+
+Example test filter file:
+
+```test.filter
+# crbug.com/417518: Get tests working w/ --site-per-process
+-BrowserTest.OtherRedirectsDontForkProcess
+-ChromeRenderProcessHostTest.*
+-ReferrerPolicyTest.HttpsRedirect
+
+# crbug.com/448592: Get extension browsertests working w/ --site-per-process
+-IsolatedAppTest.CookieIsolation
+-IsolatedAppTest.CrossProcessClientRedirect
+-IsolatedAppTest.IsolatedAppProcessModel
+-IsolatedAppTest.SubresourceCookieIsolation
+```
+
+## Usage
+
+When running tests on desktop platforms, the test filter file can be specified
+using `--test-launcher-filter-file` command line flag. Example test invocation:
+
+```bash
+$ out/dbg/content_browsertests \
+    --site-per-process \
+    --test-launcher-filter-file=testing/buildbot/filters/site-per-process.content_browsertests.filter
+```
+
+When running tests on Android, the test filter file can be specified using
+`--gtest-filter-file` command line flag. Example test invocation:
+
+```bash
+$ out/android/bin/run_content_browsertests \
+    --test-arguments=--site-per-process \
+    --gtest-filter-file=testing/buildbot/filters/site-per-process.content_browsertests.filter
+```
+
+## Applicability
+
+Test filter files described here are currently only supported for gtest-based
+tests.
+
+For excluding layout tests for specific command line flags of `content_shell`,

[alexmos, 2016/11/03 21:30:58]

nit: maybe simplify to "For excluding layout tests when running with a
particular command line flag, see..."?

[Łukasz Anforowicz, 2016/11/03 22:00:15]

Done.

+see `third_party/WebKit/LayoutTests/FlagExpectations/README.txt`.
+
+## Adding new test filter files
+
+### File names
+
+Please use the following suggestions when naming the new file:

[alexmos, 2016/11/03 21:30:58]

how about s/suggestions/conventions/ :)

[Łukasz Anforowicz, 2016/11/03 22:00:15]

Done.

+
+-   Please include the name of the test executable (e.g.
+    `content_browsertests`).
+-   Please use `.filter` suffix / extension.

[alexmos, 2016/11/03 21:30:58]

nit: "suffix / extension" - just pick one?

[Łukasz Anforowicz, 2016/11/03 22:00:15]

Done.

+-   Feel free to add other relevant things into the file name (e.g. the mode the
+    file applies to - for example `site-per-process`).
+
+### Build dependencies
+
+When adding a new file, please remember to update `data` dependencies of the
+relevant test target. This will help ensure that the test filter file ends up in
+the right place on the bot running the tests.
+
+For example - when adding a new test filter file for `content_browsertests`
+please update `content/test/BUILD.gn` to cover the new test file as a `data`
+dependency of `content_browsertests` target.
+
+Example - `content/test/BUILD.gn`:
+
+```BUILD.gn
+test("content_browsertests") {
+...
+  data = []
+...
+  # Adding all //testing/buildbot/filters/*.content_browsertests.*filter files
+  # as a dependency.
+  #
+  # They might not be used on all platforms (e.g. there is no mac bot coverage
+  # for --site-per-process today), but for simplicity we just include all of
+  # them below (doing this should help avoid unpleasant surprises when a bot
+  # config is switched in testing/buildbot/chromium.fyi.json without
+  # corresponding dependency changes here - see https://crbug.com/661447).
+  #
+  # To refresh, run the following command in bash:
+  # $ for i in $( \
+  #     find testing/buildbot/filters -name '*.content_browsertests.*filter'); \
+  #   do echo "    \"//$i\","; done | sort
+  data += [
+    "//testing/buildbot/filters/browser-side-navigation.linux.content_browsertests.filter",
+    "//testing/buildbot/filters/cast-linux.content_browsertests.filter",
+    "//testing/buildbot/filters/isolate-extensions.content_browsertests.filter",
+    "//testing/buildbot/filters/site-per-process.content_browsertests.filter",
+  ]
+```
+
+[gtest_filter]: https://github.com/google/googletest/blob/master/googletest/docs/AdvancedGuide.md#running-a-subset-of-the-tests