Skip to content

Commit f9dc868

Browse files
nik9000nik9000
authored
Docs: Test examples that recreate lang analyzers (elastic#29535)
We have a pile of documentation describing how to rebuild the built in language analyzers and, previously, our documentation testing framework made sure that the examples successfully built *an* analyzer but they didn't assert that the analyzer built by the documentation matches the built in anlayzer. Unsuprisingly, some of the examples aren't quite right. This adds a mechanism that tests that the analyzers built by the docs. The mechanism is fairly simple and brutal but it seems to be working: build a hundred random unicode sequences and send them through the `_analyze` API with the rebuilt analyzer and then again through the built in analyzer. Then make sure both APIs return the same results. Each of these calls to `_anlayze` takes about 20ms on my laptop which seems fine.
1 parent 2228e6e commit f9dc868

File tree

9 files changed

+344
-58
lines changed

9 files changed

+344
-58
lines changed

‎buildSrc/src/main/groovy/org/elasticsearch/gradle/doc/RestTestsFromSnippetsTask.groovy

+9-2
Original file line numberDiff line numberDiff line change
@@ -141,9 +141,11 @@ public class RestTestsFromSnippetsTask extends SnippetsTask {
141141
private static final String SYNTAX = {
142142
String method = /(?<method>GET|PUT|POST|HEAD|OPTIONS|DELETE)/
143143
String pathAndQuery = /(?<pathAndQuery>[^\n]+)/
144-
String badBody = /GET|PUT|POST|HEAD|OPTIONS|DELETE|#/
144+
String badBody = /GET|PUT|POST|HEAD|OPTIONS|DELETE|startyaml|#/
145145
String body = /(?<body>(?:\n(?!$badBody)[^\n]+)+)/
146-
String nonComment = /$method\s+$pathAndQuery$body?/
146+
String rawRequest = /(?:$method\s+$pathAndQuery$body?)/
147+
String yamlRequest = /(?:startyaml(?s)(?<yaml>.+?)(?-s)endyaml)/
148+
String nonComment = /(?:$rawRequest|$yamlRequest)/
147149
String comment = /(?<comment>#.+)/
148150
/(?:$comment|$nonComment)\n+/
149151
}()
@@ -333,6 +335,11 @@ public class RestTestsFromSnippetsTask extends SnippetsTask {
333335
// Comment
334336
return
335337
}
338+
String yamlRequest = matcher.group("yaml");
339+
if (yamlRequest != null) {
340+
current.println(yamlRequest)
341+
return
342+
}
336343
String method = matcher.group("method")
337344
String pathAndQuery = matcher.group("pathAndQuery")
338345
String body = matcher.group("body")

‎docs/README.asciidoc

+17
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,23 @@ for its modifiers:
6868
but rather than the setup defined in `docs/build.gradle` the setup is defined
6969
right in the documentation file.
7070
71+
In addition to the standard CONSOLE syntax these snippets can contain blocks
72+
of yaml surrounded by markers like this:
73+
74+
```
75+
startyaml
76+
- compare_analyzers: {index: thai_example, first: thai, second: rebuilt_thai}
77+
endyaml
78+
```
79+
80+
This allows slightly more expressive testing of the snippets. Since that syntax
81+
is not supported by CONSOLE the usual way to incorporate it is with a
82+
`// TEST[s//]` marker like this:
83+
84+
```
85+
// TEST[s/\n$/\nstartyaml\n - compare_analyzers: {index: thai_example, first: thai, second: rebuilt_thai}\nendyaml\n/]
86+
```
87+
7188
Any place you can use json you can use elements like `$body.path.to.thing`
7289
which is replaced on the fly with the contents of the thing at `path.to.thing`
7390
in the last response.

‎docs/build.gradle

+2
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,8 @@ buildRestTests.docs = fileTree(projectDir) {
6060
exclude 'build.gradle'
6161
// That is where the snippets go, not where they come from!
6262
exclude 'build'
63+
// Just syntax examples
64+
exclude 'README.asciidoc'
6365
}
6466

6567
Closure setupTwitter = { String name, int count ->

0 commit comments

Comments
 (0)