Added Required Tests section to README. Removed JSON from tests.

mongodb · Sep 27, 2024 · 2d4ea72 · 2d4ea72
1 parent f50677b
commit 2d4ea72
Show file tree

Hide file tree

Showing 4 changed files with 34 additions and 28 deletions.
diff --git a/source/bson-binary-vector/tests/README.md b/source/bson-binary-vector/tests/README.md
@@ -3,31 +3,29 @@
 The JSON files in this directory tree are platform-independent tests that drivers can use to prove their conformance to
 the specification.
 
-These tests focus on the roundtrip of the list numbers as input/output, along with their data type and byte padding.
+These tests focus on the roundtrip of the list of numbers as input/output, along with their data type and byte padding.
 
 Additional tests exist in `bson_corpus/tests/binary.json` but do not sufficiently test the end-to-end process of Vector
 to BSON. For this reason, drivers must create a bespoke test runner for the vector subtype.
 
-Each test case here pertains to a single vector. The inputs required to create the Binary BSON object are defined, and
-when valid, the Canonical BSON and Extended JSON representations are included for comparison.
-
-## Version
-
-Files in the "specifications" repository have no version scheme. They are not tied to a MongoDB server version.
-
 ## Format
 
+The test data corpus consists of a JSON file for each data type (dtype). Each file contains a number of test cases,
+under the top-level key "tests". Each test case pertains to a single vector. The keys provide the specification of the
+vector. Valid cases also include the Canonical BSON format of a document {test_key: binary}. The "test_key" is common,
+and specified at the top level.
+
 #### Top level keys
 
 Each JSON file contains three top-level keys.
 
 - `description`: human-readable description of what is in the file
-- `test_key`: Field name used when decoding/encoding a BSON document containing the single BSON Binary for the test
+- `test_key`: name used for key when encoding/decoding a BSON document containing the single BSON Binary for the test
   case. Applies to *every* case.
 - `tests`: array of test case objects, each of which have the following keys. Valid cases will also contain additional
   binary and json encoding values.
 
-#### Keys of tests objects
+#### Keys of individual tests cases
 
 - `description`: string describing the test.
 - `valid`: boolean indicating if the vector, dtype, and padding should be considered a valid input.
@@ -36,5 +34,21 @@ Each JSON file contains three top-level keys.
 - `dtype_alias`: (optional) string defining the data dtype, perhaps as Enum.
 - `padding`: (optional) integer for byte padding. Defaults to 0.
 - `canonical_bson`: (required if valid is true) an (uppercase) big-endian hex representation of a BSON byte string.
-- `canonical_extjson`: (required if valid is true) string containing a Canonical Extended JSON document. Because this is
-  itself embedded as a *string* inside a JSON document, characters like quote and backslash are escaped.
+
+## Required tests
+
+To prove correct in a valid case (`valid: true`), one MUST
+
+- decode the canonical_bson into its binary form, and then assert that the numeric values, dtype, and padding all match
+  those provided in the JSON.
+- encode a document from the numeric values, dtype, and padding, along with the "test_key", and assert this matches the
+  canonical_bson string.
+
+To prove correct in an invalid case (`valid:false`), one MUST
+
+- raise an exception when attempting to encode a document from the numeric values, dtype, and padding.
+
+## FAQ
+
+- What MongoDB Server version does this apply to?
+  - Files in the "specifications" repository have no version scheme. They are not tied to a MongoDB server version.
diff --git a/source/bson-binary-vector/tests/float32.json b/source/bson-binary-vector/tests/float32.json
@@ -9,8 +9,7 @@
       "dtype_hex": "0x27",
       "dtype_alias": "FLOAT32",
       "padding": 0,
-      "canonical_bson": "1C00000005766563746F72000A0000000927000000FE420000E04000", 
-      "canonical_extjson": "{\"vector\": {\"$binary\": {\"base64\": \"JwAAAP5CAADgQA==\", \"subType\": \"09\"}}}"
+      "canonical_bson": "1C00000005766563746F72000A0000000927000000FE420000E04000"
     },
     {
       "description": "Empty Vector FLOAT32",
@@ -19,8 +18,7 @@
       "dtype_hex": "0x27",
       "dtype_alias": "FLOAT32",
       "padding": 0,
-      "canonical_bson": "1400000005766563746F72000200000009270000",
-      "canonical_extjson": "{\"vector\": {\"$binary\": {\"base64\": \"JwA=\", \"subType\": \"09\"}}}"
+      "canonical_bson": "1400000005766563746F72000200000009270000"
     },
     {
       "description": "Infinity Vector FLOAT32",
@@ -29,8 +27,7 @@
       "dtype_hex": "0x27",
       "dtype_alias": "FLOAT32",
       "padding": 0,
-      "canonical_bson": "2000000005766563746F72000E000000092700000080FF000000000000807F00",
-      "canonical_extjson": "{\"vector\": {\"$binary\": {\"base64\": \"JwAAAID/AAAAAAAAgH8=\", \"subType\": \"09\"}}}"
+      "canonical_bson": "2000000005766563746F72000E000000092700000080FF000000000000807F00"
     },
     {
       "description": "FLOAT32 with padding",

diff --git a/source/bson-binary-vector/tests/int8.json b/source/bson-binary-vector/tests/int8.json
@@ -9,8 +9,7 @@
       "dtype_hex": "0x03",
       "dtype_alias": "INT8",
       "padding": 0,
-      "canonical_bson": "1600000005766563746F7200040000000903007F0700",
-      "canonical_extjson": "{\"vector\": {\"$binary\": {\"base64\": \"AwB/Bw==\", \"subType\": \"09\"}}}"
+      "canonical_bson": "1600000005766563746F7200040000000903007F0700"
     },
     {
       "description": "Empty Vector INT8",
@@ -19,8 +18,7 @@
       "dtype_hex": "0x03",
       "dtype_alias": "INT8",
       "padding": 0,
-      "canonical_bson": "1400000005766563746F72000200000009030000",
-      "canonical_extjson": "{\"vector\": {\"$binary\": {\"base64\": \"AwA=\", \"subType\": \"09\"}}}"
+      "canonical_bson": "1400000005766563746F72000200000009030000"
     },
     {
       "description": "Overflow Vector INT8",

diff --git a/source/bson-binary-vector/tests/packed_bit.json b/source/bson-binary-vector/tests/packed_bit.json
@@ -9,8 +9,7 @@
       "dtype_hex": "0x10",
       "dtype_alias": "PACKED_BIT",
       "padding": 0,
-      "canonical_bson": "1600000005766563746F7200040000000910007F0700",
-      "canonical_extjson": "{\"vector\": {\"$binary\": {\"base64\": \"EAB/Bw==\", \"subType\": \"09\"}}}"
+      "canonical_bson": "1600000005766563746F7200040000000910007F0700"
     },
     {
       "description": "Empty Vector PACKED_BIT",
@@ -19,8 +18,7 @@
       "dtype_hex": "0x10",
       "dtype_alias": "PACKED_BIT",
       "padding": 0,
-      "canonical_bson": "1400000005766563746F72000200000009100000",
-      "canonical_extjson": "{\"vector\": {\"$binary\": {\"base64\": \"EAA=\", \"subType\": \"09\"}}}"
+      "canonical_bson": "1400000005766563746F72000200000009100000"
     },
     {
       "description": "PACKED_BIT with padding",
@@ -29,8 +27,7 @@
       "dtype_hex": "0x10",
       "dtype_alias": "PACKED_BIT",
       "padding": 3,
-      "canonical_bson": "1600000005766563746F7200040000000910037F0700",
-      "canonical_extjson": "{\"vector\": {\"$binary\": {\"base64\": \"EAN/Bw==\", \"subType\": \"09\"}}}"
+      "canonical_bson": "1600000005766563746F7200040000000910037F0700"
     },
     {
       "description": "Overflow Vector PACKED_BIT",