Import wpt@e1ad3cc6894b20da0a5d7dddf431c9e7848d0544

third_party/WebKit/LayoutTests/imported/wpt/annotation-protocol/README.md

Index: third_party/WebKit/LayoutTests/imported/wpt/annotation-protocol/README.md
diff --git a/third_party/WebKit/LayoutTests/imported/wpt/annotation-protocol/README.md b/third_party/WebKit/LayoutTests/imported/wpt/annotation-protocol/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..d0ec93573fedefe140a4052bf448df5edd5cebf3
--- /dev/null
+++ b/third_party/WebKit/LayoutTests/imported/wpt/annotation-protocol/README.md
@@ -0,0 +1,86 @@
+Annotation-Protocol: Tests for the Web Annotation Protocol
+==========================================================
+
+The [Web Annotation Protocol](https://www.w3.org/TR/annotation-protocol)
+specification presents set of messages to allow Annotation clients and servers
+to interact seamlessly.
+
+The purpose of these tests is to help validate that clients send and are
+capable of receiving correctly formatted messages, and that servers are
+able to receive and respond to correctly structured requests.
+
+The general approach for this testing is to enable both manual and
+automated testing. However, since the specification has no actual user
+interface requirements, there is no general automation mechanism that
+can be presented for testing clients.  Also the server tests need to be
+pointed at a server implementation to exercise.  However, once provided
+the basic information, testing is automated.
+
+Implementors could take advantage of the plumbing we provide here to
+help their implementations talk to the endpoint we provide or exercise
+their endpoint with the provided server tests.  This assumes knowledge
+of the requirements of each test / collection of tests so that the input
+data is relevant.  Each test or test collection contains information
+sufficient for the task.
+
+With regard to server tests, the browser tests we provide can be
+pointed at an endpoint and will exercise that endpoint using well
+defined messages.  This is done semi-automatically, although some set-up
+is required.
+
+Running Tests
+-------------
+
+In the case of this test collection, we will be initially creating manual
+tests.  These will automatically determine pass or fail and generate output for
+the main WPT window.  The plan is to minimize the number of such tests to
+ease the burden on the testers while still exercising all the features.
+
+The workflow for running these tests is something like:
+
+1. Start up the test driver window and select the annotation-protocol tests -
+   either client or server - then click "Start".
+2. A window pops up that shows a test - the description of which tells the
+   tester what is required.  The window will contain fields into which some
+   information is provided.
+3. In the case of client testing the tester (presumably in another window) brings up their
+   annotation client and points it at the supplied endpoint.  They they perform the
+   action specified (annotating content in the test window, requesting an annotation from the server, etc.).
+4. The server receives the information from the client, evaluates it, and reports the result of testing.
+   In the event of multi-step messages, the cycle repeats until complete.
+5. Repeat steps 2-4 until done.
+6. Download the JSON format report of test results, which can then be visually
+   inspected, reported on using various tools, or passed on to W3C for
+   evaluation and collection in the Implementation Report via github.
+
+**Remember that while these tests are written to help exercise implementations,
+their other (important) purpose is to increase confidence that there are
+interoperable implementations.** So, implementers are our audience, but these
+tests are not meant to be a comprehensive collection of tests for an implementor.
+The bulk of the tests are manual because there are no UI requirements in the
+Recommendation that would make it possible to effectively stimulate every client portably.
+
+Having said that, because the structure of these "manual" tests is very rigid,
+it is possible for an implementer who understands test automation to use an
+open source tool such as [Selenium](http://www.seleniumhq.org/) to run these
+"manual" tests against their implementation - exercising their implementation
+against content they provide to create annotations and feed the data into our
+test input field and run the test.
+
+Capturing and Reporting Results
+-------------------------------
+
+As tests are run against implementations, if the results of testing are
+submitted to [test-results](https://github.com/w3c/test-results/) then they will
+be automatically included in documents generated by
+[wptreport](https://www.github.com/w3c/wptreport). The same tool can be used
+locally to view reports about recorded results.
+
+Automating Test Execution
+-------------------------
+
+Writing Tests
+-------------
+
+If you are interested in writing tests for this environment, see the
+associated [CONTRIBUTING](CONTRIBUTING.md) document.