diff --git a/buildSrc/src/main/groovy/org/elasticsearch/gradle/doc/RestTestsFromSnippetsTask.groovy b/buildSrc/src/main/groovy/org/elasticsearch/gradle/doc/RestTestsFromSnippetsTask.groovy index f266eaaa10446..750472acea8fa 100644 --- a/buildSrc/src/main/groovy/org/elasticsearch/gradle/doc/RestTestsFromSnippetsTask.groovy +++ b/buildSrc/src/main/groovy/org/elasticsearch/gradle/doc/RestTestsFromSnippetsTask.groovy @@ -31,9 +31,20 @@ class RestTestsFromSnippetsTask extends SnippetsTask { */ private static final List BAD_LANGUAGES = ['json', 'javascript'] + /** + * Test setups defined in the build instead of the docs so they can be + * shared between many doc files. + */ @Input Map setups = new HashMap() + /** + * Test teardowns defined in the build instead of the docs so they can be + * shared between many doc files. + */ + @Input + Map teardowns = new HashMap() + /** * A list of files that contain snippets that *probably* should be * converted to `// CONSOLE` but have yet to be converted. If a file is in @@ -281,19 +292,40 @@ class RestTestsFromSnippetsTask extends SnippetsTask { } body(test, false) + + if (test.teardown != null) { + teardown(test) + } } private void setup(final Snippet snippet) { // insert a setup defined outside of the docs - for (final String setupName : snippet.setup.split(',')) { - final String setup = setups[setupName] + for (final String name : snippet.setup.split(',')) { + final String setup = setups[name] if (setup == null) { - throw new InvalidUserDataException("Couldn't find setup for $snippet") + throw new InvalidUserDataException( + "Couldn't find named setup $name for $snippet" + ) } + current.println("# Named setup ${name}") current.println(setup) } } + private void teardown(final Snippet snippet) { + // insert a teardown defined outside of the docs + for (final String name : snippet.teardown.split(',')) { + final String teardown = teardowns[name] + if (teardown == null) { + throw new InvalidUserDataException( + "Couldn't find named teardown $name for $snippet" + ) + } + current.println("# Named teardown ${name}") + current.println(teardown) + } + } + private void response(Snippet response) { if (null == response.skip) { current.println(" - match: ") diff --git a/buildSrc/src/main/groovy/org/elasticsearch/gradle/doc/SnippetsTask.groovy b/buildSrc/src/main/groovy/org/elasticsearch/gradle/doc/SnippetsTask.groovy index b70f910e7249e..2a6d88269b52b 100644 --- a/buildSrc/src/main/groovy/org/elasticsearch/gradle/doc/SnippetsTask.groovy +++ b/buildSrc/src/main/groovy/org/elasticsearch/gradle/doc/SnippetsTask.groovy @@ -32,10 +32,11 @@ class SnippetsTask extends DefaultTask { private static final String CATCH = /catch:\s*((?:\/[^\/]+\/)|[^ \]]+)/ private static final String SKIP = /skip:([^\]]+)/ private static final String SETUP = /setup:([^ \]]+)/ + private static final String TEARDOWN = /teardown:([^ \]]+)/ private static final String WARNING = /warning:(.+)/ private static final String NON_JSON = /(non_json)/ private static final String TEST_SYNTAX = - /(?:$CATCH|$SUBSTITUTION|$SKIP|(continued)|$SETUP|$WARNING|(skip_shard_failures)) ?/ + /(?:$CATCH|$SUBSTITUTION|$SKIP|(continued)|$SETUP|$TEARDOWN|$WARNING|(skip_shard_failures)) ?/ /** * Action to take on each snippet. Called with a single parameter, an @@ -226,10 +227,14 @@ class SnippetsTask extends DefaultTask { return } if (it.group(7) != null) { - snippet.warnings.add(it.group(7)) + snippet.teardown = it.group(7) return } if (it.group(8) != null) { + snippet.warnings.add(it.group(8)) + return + } + if (it.group(9) != null) { snippet.skipShardsFailures = true return } @@ -341,6 +346,7 @@ class SnippetsTask extends DefaultTask { String language = null String catchPart = null String setup = null + String teardown = null boolean curl List warnings = new ArrayList() boolean skipShardsFailures = false @@ -372,6 +378,9 @@ class SnippetsTask extends DefaultTask { if (setup) { result += "[setup:$setup]" } + if (teardown) { + result += "[teardown:$teardown]" + } for (String warning in warnings) { result += "[warning:$warning]" } diff --git a/docs/README.asciidoc b/docs/README.asciidoc index b17cd778b96c5..4d573c21ee4d7 100644 --- a/docs/README.asciidoc +++ b/docs/README.asciidoc @@ -79,9 +79,13 @@ used for its modifiers: considered tests anyway but this is useful for explicitly documenting the reason why the test shouldn't be run. * `// TEST[setup:name]`: Run some setup code before running the snippet. This - is useful for creating and populating indexes used in the snippet. The setup - code is defined in `docs/build.gradle`. See `// TESTSETUP` below for a - similar feature. + is useful for creating and populating indexes used in the snippet. The `name` + is split on `,` and looked up in the `setups` defined in `docs/build.gradle`. + See `// TESTSETUP` below for a similar feature. + * `// TEST[teardown:name]`: Run some teardown code after the snippet. + This is useful for performing hidden cleanup, such as deleting index templates. The + `name` is split on `,` and looked up in the `teardowns` defined in + `docs/build.gradle`. See `// TESTSETUP` below for a similar feature. * `// TEST[warning:some warning]`: Expect the response to include a `Warning` header. If the response doesn't include a `Warning` header with the exact text then the test fails. If the response includes `Warning` headers that diff --git a/docs/build.gradle b/docs/build.gradle index 327b3902f447f..bcaff515d408e 100644 --- a/docs/build.gradle +++ b/docs/build.gradle @@ -1295,6 +1295,30 @@ setups['remote_cluster_and_leader_index'] = setups['remote_cluster'] + ''' index.soft_deletes.enabled: true ''' +setups['remote_cluster_and_leader_index_and_follower_index'] = setups['remote_cluster_and_leader_index'] + ''' + - do: + raw: + method: PUT + path: 'follower_index/_ccr/follow' + wait_for_active_shards: 1 + body: | + { + "remote_cluster" : "remote_cluster", + "leader_index" : "leader_index" + } + - is_true: follow_index_created + - is_true: follow_index_shards_acked + - is_true: index_following_started +''' + +teardowns['pause_follow'] = ''' + - do: + raw: + method: POST + path: 'follower_index/_ccr/pause_follow' + - is_true: acknowledged +''' + setups['seats'] = ''' - do: indices.create: diff --git a/docs/reference/ccr/managing.asciidoc b/docs/reference/ccr/managing.asciidoc index bb07375a17224..c1781508c61b2 100644 --- a/docs/reference/ccr/managing.asciidoc +++ b/docs/reference/ccr/managing.asciidoc @@ -1,27 +1,6 @@ [role="xpack"] [testenv="platinum"] -////////////////////////// - -[source,console] --------------------------------------------------- -PUT /follower_index/_ccr/follow?wait_for_active_shards=1 -{ - "remote_cluster" : "remote_cluster", - "leader_index" : "leader_index" -} --------------------------------------------------- -// TESTSETUP -// TEST[setup:remote_cluster_and_leader_index] - -[source,console] --------------------------------------------------- -POST /follower_index/_ccr/pause_follow --------------------------------------------------- -// TEARDOWN - -////////////////////////// - [[ccr-managing]] === Manage {ccr} Use the following information to manage {ccr} tasks, such as inspecting @@ -135,6 +114,7 @@ PUT /follower_index/_ccr/follow?wait_for_active_shards=1 "leader_index" : "leader_index" } ---------------------------------------------------------------------- +// TEST[setup:remote_cluster_and_leader_index_and_follower_index teardown:pause_follow] ==== [[ccr-terminate-replication]]