|
| 1 | +# Testing Binary subtype 9: Vector |
| 2 | + |
| 3 | +The JSON files in this directory tree are platform-independent tests that drivers can use to prove their conformance to |
| 4 | +the specification. |
| 5 | + |
| 6 | +These tests focus on the roundtrip of the list of numbers as input/output, along with their data type and byte padding. |
| 7 | + |
| 8 | +Additional tests exist in `bson_corpus/tests/binary.json` but do not sufficiently test the end-to-end process of Vector |
| 9 | +to BSON. For this reason, drivers must create a bespoke test runner for the vector subtype. |
| 10 | + |
| 11 | +## Format |
| 12 | + |
| 13 | +The test data corpus consists of a JSON file for each data type (dtype). Each file contains a number of test cases, |
| 14 | +under the top-level key "tests". Each test case pertains to a single vector. The keys provide the specification of the |
| 15 | +vector. Valid cases also include the Canonical BSON format of a document {test_key: binary}. The "test_key" is common, |
| 16 | +and specified at the top level. |
| 17 | + |
| 18 | +#### Top level keys |
| 19 | + |
| 20 | +Each JSON file contains three top-level keys. |
| 21 | + |
| 22 | +- `description`: human-readable description of what is in the file |
| 23 | +- `test_key`: name used for key when encoding/decoding a BSON document containing the single BSON Binary for the test |
| 24 | + case. Applies to *every* case. |
| 25 | +- `tests`: array of test case objects, each of which have the following keys. Valid cases will also contain additional |
| 26 | + binary and json encoding values. |
| 27 | + |
| 28 | +#### Keys of individual tests cases |
| 29 | + |
| 30 | +- `description`: string describing the test. |
| 31 | +- `valid`: boolean indicating if the vector, dtype, and padding should be considered a valid input. |
| 32 | +- `vector`: (required if valid is true) list of numbers |
| 33 | +- `dtype_hex`: string defining the data type in hex (e.g. "0x10", "0x27") |
| 34 | +- `dtype_alias`: (optional) string defining the data dtype, perhaps as Enum. |
| 35 | +- `padding`: (optional) integer for byte padding. Defaults to 0. |
| 36 | +- `canonical_bson`: (required if valid is true) an (uppercase) big-endian hex representation of a BSON byte string. |
| 37 | + |
| 38 | +## Required tests |
| 39 | + |
| 40 | +#### To prove correct in a valid case (`valid: true`), one MUST |
| 41 | + |
| 42 | +- encode a document from the numeric values, dtype, and padding, along with the "test_key", and assert this matches the |
| 43 | + canonical_bson string. |
| 44 | +- decode the canonical_bson into its binary form, and then assert that the numeric values, dtype, and padding all match |
| 45 | + those provided in the JSON. |
| 46 | + |
| 47 | +Note: For floating point number types, exact numerical matches may not be possible. Drivers that natively support the |
| 48 | +floating-point type being tested (e.g., when testing float32 vector values in a driver that natively supports float32), |
| 49 | +MUST assert that the input float array is the same after encoding and decoding. |
| 50 | + |
| 51 | +#### To prove correct in an invalid case (`valid:false`), one MUST |
| 52 | + |
| 53 | +- if the vector field is present, raise an exception when attempting to encode a document from the numeric values, |
| 54 | + dtype, and padding. |
| 55 | +- if the canonical_bson field is present, raise an exception when attempting to deserialize it into the corresponding |
| 56 | + numeric values, as the field contains corrupted data. |
| 57 | + |
| 58 | +## FAQ |
| 59 | + |
| 60 | +- What MongoDB Server version does this apply to? |
| 61 | + - Files in the "specifications" repository have no version scheme. They are not tied to a MongoDB server version. |
0 commit comments