github-mirrors/elasticsearch
1
0
Fork 0
mirror of https://github.com/elastic/elasticsearch.git synced 2025-06-28 09:28:55 -04:00
Code Issues Projects Releases Packages Wiki Activity

Update README.asciidoc (#96455) (#121028)

Browse source 
Co-authored-by: ARPIT SHARMA <93235104+ARPIT2128@users.noreply.github.com>
This commit is contained in:
Liam Thompson 2025-01-28 15:01:12 +01:00 • committed by GitHub
parent 8e9cccba6a
commit c193f6b03c
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 9 additions and 10 deletions
Download patch file Download diff file Expand all files Collapse all files

19
docs/README.asciidoc
View file

@ -157,16 +157,15 @@ used for its modifiers:
* `// TESTRESPONSE[skip:reason]`: Skip the assertions specified by this
response.
* `// TESTSETUP`: Marks this snippet as the "setup" for all other snippets in
this file. This is a somewhat natural way of structuring documentation. You
say "this is the data we use to explain this feature" then you add the
snippet that you mark `// TESTSETUP` and then every snippet will turn into
a test that runs the setup snippet first. See the "painless" docs for a file
that puts this to good use. This is fairly similar to `// TEST[setup:name]`
but rather than the setup defined in `docs/build.gradle` the setup is defined
right in the documentation file. In general, we should prefer `// TESTSETUP`
over `// TEST[setup:name]` because it makes it more clear what steps have to
be taken before the examples will work. Tip: `// TESTSETUP` can only be used
on the first snippet of a document.
this file. In order to enhance clarity and simplify understanding for readers,
a straightforward approach involves marking the first snippet in the documentation file with the
`// TESTSETUP` marker. By doing so, it clearly indicates that this particular snippet serves as the setup
or preparation step for all subsequent snippets in the file.
This helps in explaining the necessary steps that need to be executed before running the examples.
Unlike the alternative convention `// TEST[setup:name]`, which relies on a setup defined in a separate file,
this convention brings the setup directly into the documentation file, making it more self-contained and reducing ambiguity.
By adopting this convention, users can easily identify and follow the correct sequence
of steps to ensure that the examples provided in the documentation work as intended.
* `// TEARDOWN`: Ends and cleans up a test series started with `// TESTSETUP` or
`// TEST[setup:name]`. You can use `// TEARDOWN` to set up multiple tests in
the same file.