Merge branch 'main' into ppl-namespace

Signed-off-by: Niyazbek Torekeldi <78027392+Tokesh@users.noreply.github.com>

.cspell

@@ -1,52 +1,8 @@
-APIV
-Boxplot
-Bobg
-Boundsdouble
-CBOR
-DNFOF
-Decompounder
-Downsample
-Downsampling
-Ewma
-Fielddata
-Formattable
-Fragmenter
-Geohex
-Gsub
-Intertransport
-Jelinek
-Kuromoji
-Lovins
-Lucene
-Millis
-Moneyball
-Multisearch
-Moneyball
-Nanos
-Nori
-ONNX
-OPENSEARCH
-OSCPU
-Oversample
-Rebalance
-Reindex
-Rethrottle
-Rolespan
-Rollup
-Rollups
-Slowlog
-Sorani
-Stringifiedboolean
-Stringifiedinteger
-Tfidf
-Tika
-Translog
-Unmanaged
-Yrtsd
 aarch
 actiongroup
 actiongroups
 aggregatable
+APIV
 argjson
 asciifolding
 authc
@@ -56,63 +12,92 @@ autocut
 backendroles
 backpressure
 beider
+Bobg
+Boundsdouble
 boxplot
+Boxplot
 caverphone
+CBOR
 charfilters
 chisquared
 chuhlomin
 cpuacct
+cuserr
 daitch
 dangoslen
 dashboardsinfo
+datarows
 decompounder
+Decompounder
 dedup
 determinized
+distilbert
+DNFOF
 docvalue
+Downsample
 downsampling
+Downsampling
 evals
 ewma
+Ewma
 faiss
 fielddata
+Fielddata
 forcemerge
+Formattable
 fragmenter
+Fragmenter
 freqs
 generateonbehalfoftoken
 geohash
 geohex
+Geohex
 geoip
 geotile
 gsub
+Gsub
 haasephonetik
 heteroscedastic
 homoscedastic
 hotthreads
+huggingface
 hybridfs
 integ
 internalusers
+Intertransport
+Jelinek
 kibanainfo
 kibanaserver
 koelnerphonetik
 kstem
 kuromoji
+Kuromoji
 languageset
+Lovins
 lucene
+Lucene
 lycheeverse
 marvinpinto
 metaphone
 mget
 millis
+Millis
 mlockall
 mmap
 mmapfs
 mmdb
 mokotoff
+Moneyball
+Moneyball
 msearch
+msmarco
 mtermvectors
 mult
+Multisearch
 multitenancy
 mxyz
 nanos
+Nanos
 nbest
 nfkc
 ngram
@@ -122,13 +107,18 @@ nodeattrs
 nodesdn
 noops
 nori
+Nori
 nysiis
+ONNX
 opendistro
 opensearch
+OPENSEARCH
 opensearchproject
 opensearchstaging
 ords
+OSCPU
 oversample
+Oversample
 performanceanalyzer
 permissionsinfo
 pipefail
@@ -137,38 +127,54 @@ prirep
 rawfile
 readingform
 rebalance
+Rebalance
 recoverysource
 reindex
+Reindex
 relo
 reloadcerts
 remotestore
 rethrottle
+Rethrottle
 rolesmapping
+Rolespan
 rollup
+Rollup
 rollups
+Rollups
 romaji
 roundtrips
+Rudnick
 ruleset
 scriptless
 securityconfig
 slowlog
+Slowlog
 slurpfile
 snapshotted
 softmax
+Sorani
 sslinfo
 stoptags
 stopwords
+Stringifiedboolean
+Stringifiedinteger
 subqueries
 subschemas
 subword
+syserr
 tdigest
 tenantinfo
 termvectors
 tfidf
+Tfidf
+Tika
 tokenfilters
 translog
+Translog
 tubone
 unigrams
+Unmanaged
 unmatch
 untriaged
 updateable
@@ -177,7 +183,4 @@ urldecode
 vectory
 whoamiprotected
 wordnet
-datarows
-syserr
-cuserr
-Rudnick
+Yrtsd

.github/opensearch-cluster/docker-compose.yml

@@ -8,6 +8,7 @@ services:
       - '9600:9600'
     environment:
       - 'OPENSEARCH_INITIAL_ADMIN_PASSWORD=${OPENSEARCH_PASSWORD:-myStrongPassword123!}'
+      - OPENSEARCH_JAVA_OPTS=${OPENSEARCH_JAVA_OPTS}
       - discovery.type=single-node
       - path.repo=/tmp/opensearch/repo
-      - plugins.index_state_management.job_interval=1
+      - plugins.index_state_management.job_interval=1

.github/workflows/test-spec.yml

@@ -26,7 +26,9 @@ jobs:
           - {version: 1.3.17, admin_password: admin}
           - {version: 2.0.0, admin_password: admin}
           - {version: 2.15.0}
-          - {version: 2.16.0, hub: opensearchstaging, ref: '@sha256:50fbfe3b95c41e92a113ada3e80513ba4524dfc8a25dc6aaeff2bbe1e1145d5f'}
+          - version: 2.16.0
+            hub: opensearchstaging
+            ref: '@sha256:50fbfe3b95c41e92a113ada3e80513ba4524dfc8a25dc6aaeff2bbe1e1145d5f'
 
     name: test-opensearch-spec (version=${{ matrix.entry.version }}, hub=${{ matrix.entry.hub || 'opensearchproject' }})
     runs-on: ubuntu-latest
@@ -36,6 +38,7 @@ jobs:
       OPENSEARCH_DOCKER_REF: ${{ matrix.entry.ref }}
       OPENSEARCH_VERSION: ${{ matrix.entry.version }}
       OPENSEARCH_PASSWORD: ${{ matrix.entry.admin_password || 'myStrongPassword123!' }}
+      OPENSEARCH_JAVA_OPTS: ${{ matrix.entry.opts }}
 
     steps:
       - name: Checkout Repo
@@ -51,7 +54,7 @@ jobs:
 
       - name: Run OpenSearch Cluster
         working-directory: .github/opensearch-cluster
-        run: docker-compose up -d
+        run: docker compose up -d
 
       - name: Run Tests
         run: |

.github/workflows/test-tools-integ.yml

@@ -34,7 +34,7 @@ jobs:
       - name: Run OpenSearch Cluster
         working-directory: .github/opensearch-cluster
         run: |
-          docker-compose up -d
+          docker compose up -d
           sleep 15
 
       - name: Setup Node.js

CHANGELOG.md

@@ -55,6 +55,9 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 - Added `plugins` to NodeInfoSettings ([#442](https://github.com/opensearch-project/opensearch-api-specification/pull/442)) 
 - Added test coverage ([#443](https://github.com/opensearch-project/opensearch-api-specification/pull/443))
 - Added `--opensearch-version` to `merger` that excludes schema elements per semver ([#428](https://github.com/opensearch-project/opensearch-api-specification/pull/428))
+- Added `retry` to `tester` to support asynchronous tasks ([453](https://github.com/opensearch-project/opensearch-api-specification/pull/453))
+- Added passing OPENSEARCH_JAVA_OPTS into the docker container used for tests ([#454](https://github.com/opensearch-project/opensearch-api-specification/pull/454))
+- Added a warning on mulitple paths being tested in the same file ([#452](https://github.com/opensearch-project/opensearch-api-specification/pull/452))
 - Added `/_plugins/_ppl`, `explain` and `stats` ([#460](https://github.com/opensearch-project/opensearch-api-specification/pull/460))
 
 ### Changed

TESTING_GUIDE.md

@@ -5,6 +5,10 @@
     - [Simple Test Story](#simple-test-story)
     - [Using Output from Previous Chapters](#using-output-from-previous-chapters)
     - [Managing Versions](#managing-versions)
+    - [Waiting for Tasks](#waiting-for-tasks)
+    - [Warnings](#warnings)
+      - [multiple-paths-detected](#multiple-paths-detected)
+      - [Suppressing Warnings](#suppressing-warnings)
 <!-- TOC -->
 
 # Spec Testing Guide
@@ -19,7 +23,7 @@ Set up an OpenSearch cluster with Docker:
 ```bash
 export OPENSEARCH_PASSWORD=<<your_password>>
 cd .github/opensearch-cluster
-docker-compose up -d
+docker compose up -d
 ```
 
 Run the tests (use `--opensearch-insecure` for a local cluster running in Docker that does not have a valid SSL certificate):
@@ -153,3 +157,55 @@ It's common to add a feature to the next version of OpenSearch. When adding a ne
 ```
 
 The [integration test workflow](.github/workflows/test-spec.yml) runs a matrix of OpenSearch versions, including the next version. Please check whether the workflow needs an update when adding version-specific tests.
+
+### Waiting for Tasks
+
+Some APIs behave asynchronously and may require a test to wait for a task to complete. This can be achived with a combination of `payload` and `retry`. 
+
+For example, an ML task returns `CREATED` when created, and `COMPLETED` when it's done. The example below will retry 3 times with an interval of 30 seconds until the task is complete. The default wait time is 1s.
+
+```yaml
+  - synopsis: Wait for task.
+    path: /_plugins/_ml/tasks/{task_id}
+    method: GET
+    parameters:
+      task_id: ${create_model.task_id}
+    response:
+      status: 200
+      payload:
+        state: COMPLETED
+    retry:
+      count: 3
+      wait: 30000
+```
+### Warnings
+
+#### multiple-paths-detected
+
+The test runner expects all tests in the same file to be variation of the same path in order to keep tests well-organized. Otherwise, a warning will be emitted.
+
+```
+WARNING Multiple paths detected, please group similar tests together and move paths not being tested to prologues or epilogues.
+  /_component_template/{name}
+  /_index_template/{name}
+  /{index}
+```
+
+#### Suppressing Warnings
+
+The test runner may generate warnings that can be suppressed with `warnings:`. For example, to suppress the multiple paths detected warning.
+
+```yaml
+- synopsis: Create an index.
+  method: PUT
+  path: /{index}
+  parameters:
+    index: movies
+- synopsis: Search the index to make sure it has been created.
+  method: POST
+  warnings:
+    multiple-paths-detected: false
+  path: /{index}/_search
+  parameters:
+    index: movies
+```