Merge branch 'master' into revise-encryption-tests

Author: mdb-ad

.github/workflows/check-schema-latest.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+
+# Change to the working directory where the schema files are located
+cd source/unified-test-format || {
+  echo "Directory source/unified-test-format not found."
+  exit 1
+}
+
+# Find the max X in schema-1.X.json
+max=0
+for file in schema-1.*.json; do
+  # Extract the version number from the filename
+  version=${file##*schema-1.}
+  version=${version%.json}
+
+  if [[ $version =~ ^[0-9]+$ ]]; then
+    # Compare the version number with the current max
+    if ((version > max)); then
+      max=$version
+    fi
+  fi
+done
+
+if ((max == 0)); then
+  echo "No schema files found."
+  exit 1
+fi
+
+# Compare that file vs schema-latest.json
+expected="schema-1.$max.json"
+if ! diff -u "$expected" schema-latest.json >/dev/null; then
+  echo "schema-latest.json is not up to date with schema-1.$max.json"
+  echo "please run 'make update-schema-latest' from source/ to update it"
+  exit 1
+fi
+
+exit 0

.github/workflows/unified-test-format-schema-check.yml

@@ -28,3 +28,5 @@ jobs:
         run: make
       - name: Check all unified tests schema version is valid
         run: bash .github/workflows/check_schema_version.sh
+      - name: Check schema-latest.json has been updated 
+        run: bash .github/workflows/check-schema-latest.sh

.pre-commit-config.yaml

@@ -23,7 +23,7 @@ repos:
       stages: [manual]
 
 - repo: https://github.com/executablebooks/mdformat
-  rev: 0.7.18
+  rev: 0.7.22
   hooks:
     - id: mdformat
       args: ["--wrap=120", "--number"]
@@ -32,7 +32,7 @@ repos:
         - mdformat-frontmatter
         - mdformat-gfm
         - mdformat-gfm-alerts
-        - mdformat-mkdocs~=3.0
+        - mdformat-mkdocs
 
 - repo: local
   hooks:
@@ -52,10 +52,10 @@ repos:
     entry: python3 scripts/check_md_html.py
 
 - repo: https://github.com/tcort/markdown-link-check
-  rev: v3.12.2
+  rev: v3.13.7
   hooks:
     - id: markdown-link-check
-      args: ["-c", "markdown_link_config.json"]
+      args: ["-q", "-c", "markdown_link_config.json"]
 
 - repo: https://github.com/rstcheck/rstcheck
   rev: v6.2.0

README.md

@@ -36,14 +36,43 @@ To run a manual hook like `shellcheck` manually, run:
 pre-commit run --all-files --hook-stage manual shellcheck
 ```
 
-## Prose test numbering
+## Prose Test Numbering
 
 When numbering prose tests, always use relative numbered bullets (`1.`). New tests must be appended at the end of the
 test list, since drivers may refer to existing tests by number.
 
 Outdated tests must not be removed completely, but may be marked as such (e.g. by striking through or replacing the
 entire test with a note (e.g. *Removed*).
 
+## Automated Test Best Practices
+
+### Immutability of Existing Tests
+
+**Do not modify existing tests**, unless they are testing incorrect behavior. Default to creating new tests or test
+files instead of altering existing ones.
+
+Test files can only be deleted once no driver runs them anymore. In the meantime, for cases where a spec change removes
+functionality:
+
+- **Unified Tests:** Use `runOnRequirements` to ensure tests are only executed by drivers supporting the required
+    functionality.
+- **Non-Unified Tests (e.g., SDAM):** Drivers should skip tests that no longer apply to them.
+
+### Test Isolation
+
+When creating a new test, only test functionality directly related to the new spec requirements. Omit irrelevant fields
+in command expectations.
+
+This makes tests more resilient against spec updates and avoids needing to change tests down the line.
+
+### Schema Version Usage
+
+Use the **lowest possible schema version** for each test.
+
+Do NOT default to using the latest unified test format schema version, as the drivers may not all implement it. Use the
+oldest schema version that supports all functionality used in the test, even if it requires creating a new test file
+with a lower schema version.
+
 ## Building Documents
 
 We use [mkdocs](https://www.mkdocs.org/) to render the documentation. To see a live view of the documentation, in a

source/Makefile

@@ -17,3 +17,16 @@ HAS_JSYAML:
 	    echo 'Error: need "npm install -g js-yaml"' 1>&2; \
 	    exit 1;                                           \
 	fi
+
+VERSION := $(shell \
+	find unified-test-format -maxdepth 1 -type f -name 'schema-1.*.json' \
+	| sed -E 's:.*/schema-1\.([0-9]+)\.json:\1:' \
+	| sort -n \
+	| tail -n1 \
+)
+
+.PHONY: update-schema-latest
+update-schema-latest:
+	cp unified-test-format/schema-1.$(VERSION).json \
+		unified-test-format/schema-latest.json
+

source/auth/auth.md

@@ -922,18 +922,18 @@ else // the valid host string contains no periods and is not "aws.amazonaws.com"
 
 Examples are provided below.
 
-| Host                           | Region     | Notes                                            |
-| ------------------------------ | ---------- | ------------------------------------------------ |
-| sts.amazonaws.com              | us-east-1  | the host is "sts.amazonaws.com"; use `us-east-1` |
-| sts.us-west-2.amazonaws.com    | us-west-2  | use the second label                             |
-| sts.us-west-2.amazonaws.com.ch | us-west-2  | use the second label                             |
-| example.com                    | com        | use the second label                             |
-| localhost                      | us-east-1  | no "`.`" character; use the default region       |
-| sts..com                       | \< Error > | second label is empty                            |
-| .amazonaws.com                 | \< Error > | starts with a period                             |
-| sts.amazonaws.                 | \< Error > | ends with a period                               |
-| ""                             | \< Error > | empty string                                     |
-| "string longer than 255"       | \< Error > | string longer than 255 bytes                     |
+| Host                           | Region    | Notes                                            |
+| ------------------------------ | --------- | ------------------------------------------------ |
+| sts.amazonaws.com              | us-east-1 | the host is "sts.amazonaws.com"; use `us-east-1` |
+| sts.us-west-2.amazonaws.com    | us-west-2 | use the second label                             |
+| sts.us-west-2.amazonaws.com.ch | us-west-2 | use the second label                             |
+| example.com                    | com       | use the second label                             |
+| localhost                      | us-east-1 | no "`.`" character; use the default region       |
+| sts..com                       | < Error > | second label is empty                            |
+| .amazonaws.com                 | < Error > | starts with a period                             |
+| sts.amazonaws.                 | < Error > | ends with a period                               |
+| ""                             | < Error > | empty string                                     |
+| "string longer than 255"       | < Error > | string longer than 255 bytes                     |
 
 #### [MongoCredential](#mongocredential) Properties