anchor.diff:  
   == Testing the REST layer
   
  -The available integration tests make use of the java API to communicate with
  -the elasticsearch nodes, using the internal binary transport (port 9300 by
  -default).
  -The REST layer is tested through specific tests that are shared between all
  -the elasticsearch official clients and consist of YAML files that describe the
  +The REST layer is tested through specific tests that are executed against
  +a cluster that is configured and initialized via Gradle. The tests
  +themselves can be written in either Java or with a YAML based DSL.
  +
  +YAML based REST tests should be preferred since these are shared between all
  +the elasticsearch official clients. The YAML based tests describe the
   operations to be executed and the obtained results that need to be tested.
   
  -The YAML files support various operators defined in the link:/rest-api-spec/src/main/resources/rest-api-spec/test/README.asciidoc[rest-api-spec] and adhere to the link:/rest-api-spec/README.markdown[Elasticsearch REST API JSON specification]
  +The YAML tests support various operators defined in the link:/rest-api-spec/src/main/resources/rest-api-spec/test/README.asciidoc[rest-api-spec] and adhere to the link:/rest-api-spec/README.markdown[Elasticsearch REST API JSON specification]
  +In order to run the the YAML tests, the relevant API specification needs
  +to be on the test classpath. Any gradle project that has support for REST
  +tests will get the primary API on it's class path. However, to better support
  +Gradle incremental builds, it is recommended to explicitly declare which
  +parts of the API the tests depend upon.
  +
  +For example:
  +---------------------------------------------------------------------------
  +restResources {
  +  restApi {
  +    includeCore '_common', 'indices', 'index', 'cluster', 'nodes', 'get', 'ingest'
  +  }
  +}
  +---------------------------------------------------------------------------
  +
  +YAML tests that include x-pack specific APIs need to explicitly declare
  +which APIs are required through a similar `includeXpack` configuration.
   
   The REST tests are run automatically when executing the "./gradlew check" command. To run only the
   REST tests use the following command:
   
   ---------------------------------------------------------------------------
  -./gradlew :distribution:archives:integ-test-zip:integTest   \
  -  -Dtests.class="org.elasticsearch.test.rest.*Yaml*IT"
  ----------------------------------------------------------------------------
  -
  -A specific test case can be run with
  -
  ----------------------------------------------------------------------------
  -./gradlew :distribution:archives:integ-test-zip:integTest \
  -  -Dtests.class="org.elasticsearch.test.rest.*Yaml*IT" \
  -  -Dtests.method="test {p0=cat.shards/10_basic/Help}"
  ----------------------------------------------------------------------------
  -
  -`*Yaml*IT` are the executable test classes that runs all the
  -yaml suites available within the `rest-api-spec` folder.
  +./gradlew :distribution:archives:integ-test-zip:integTestRunner \
  + --tests "org.elasticsearch.test.rest.IntegTestZipClientYamlTestSuiteIT"
  +---------------------------------------------------------------------------
  +
  +A specific test case can be run with the following command:
  +
  +---------------------------------------------------------------------------
  +./gradlew ':distribution:archives:integ-test-zip:integTestRunner' \
  +  --tests "org.elasticsearch.test.rest.IntegTestZipClientYamlTestSuiteIT" \
  +  -Dtests.method="test {p0=cat.segments/10_basic/Help}"
  +---------------------------------------------------------------------------
   
   The REST tests support all the options provided by the randomized runner, plus the following:
   
  
positive.code: * **`ESIntegTestCase`**: An integration test case that creates a cluster that
    might have multiple nodes.
  * **`ESRestTestCase`**: An integration tests that interacts with an external
    cluster via the REST API. For instance, YAML tests run via sub classes of
    `ESRestTestCase`.
  
  === Good practices
  
  
negative.code: 
  The Elasticsearch docs are in AsciiDoc format. You can test and build the docs
  locally using the Elasticsearch documentation build process. See
  https://github.com/elastic/docs.
  