|
| 1 | +GridFS Tests |
| 2 | +============ |
| 3 | + |
| 4 | +The YAML and JSON files in this directory are platform-independent tests |
| 5 | +meant to exercise a driver's implementation of GridFS. |
| 6 | + |
| 7 | +Converting to JSON |
| 8 | +================== |
| 9 | + |
| 10 | +The tests are written in YAML because it is easier for humans to write |
| 11 | +and read, and because YAML supports a standard comment format. Each test |
| 12 | +is also provided in JSON format because in some languages it is easier |
| 13 | +to parse JSON than YAML. |
| 14 | + |
| 15 | +If you modify any test, you should modify the YAML file and then |
| 16 | +regenerate the JSON file from it. |
| 17 | + |
| 18 | +One way to convert the files is using an online web page. I used: |
| 19 | + |
| 20 | +http://www.json2yaml.com/ |
| 21 | + |
| 22 | +It's advertised as a JSON to YAML converter but it can be used in either direction. |
| 23 | + |
| 24 | +Note: the yaml2json utility from npm is not capable of converting these YAML tests |
| 25 | +because it doesn't implement the full YAML spec. |
| 26 | + |
| 27 | +Format |
| 28 | +====== |
| 29 | + |
| 30 | +Each test file has two top level sections: |
| 31 | + |
| 32 | +1. data |
| 33 | +2. tests |
| 34 | + |
| 35 | +The data section defines the initial contents of the files and chunks |
| 36 | +collections for all tests in that file. |
| 37 | + |
| 38 | +The tests section defines the tests to be run. The format of the tests |
| 39 | +section will vary slightly depending on what tests are being defined. |
| 40 | +In general, they will have the following sections: |
| 41 | + |
| 42 | +1. description |
| 43 | +2. arrange |
| 44 | +3. act |
| 45 | +4. assert |
| 46 | + |
| 47 | +The arrange section, if present, defines changes to be made to the |
| 48 | +initial contents of the files and chunks collections (as defined by |
| 49 | +the data section) before this particular test is run. These changes |
| 50 | +are described in the form of write commands that can be sent directly |
| 51 | +to MongoDB. |
| 52 | + |
| 53 | +The act section defines what operation (with which arguments) should |
| 54 | +be performed. |
| 55 | + |
| 56 | +The assert section defines what should be true at the end of the test. |
| 57 | +This includes checking the return value of the operation, as well as |
| 58 | +checking the expected contents of the files and chunks collections. The |
| 59 | +expected contents of the files and chunks collections are described |
| 60 | +in the form of write commands that modify collections named |
| 61 | +expected.files and expected.chunks. Before running these commands, |
| 62 | +load the initial files and chunks documents into the expected.files |
| 63 | +and expected.chunks collections and then run the commands. At that point |
| 64 | +you can assert that fs.files and expected.files are the same, and that |
| 65 | +expected.chunks and fs.chunks are the same. |
| 66 | + |
| 67 | +For operations that are expected to succeed the assert section contains |
| 68 | +a "result" element describing the expected result. For operations |
| 69 | +that are expected to fail the assert section contains an "error" |
| 70 | +element describing the expected failure. |
| 71 | + |
| 72 | +The "result" element is either the expected result when it is possible to |
| 73 | +know the result in advance, or it is the special value "&result" |
| 74 | +which means that we expect a result (not a failure) but the actual |
| 75 | +value of the result could be anything. The notation "&result" is |
| 76 | +modeled after YAML syntax for defining an anchor, and the |
| 77 | +result value may be referenced later in the assert section as |
| 78 | +"*result". |
| 79 | +
|
| 80 | +Another special notation in the assert section is "*actual", which |
| 81 | +is used when the value of a field cannot be known in advance of the |
| 82 | +test, so the assert logic should accept whatever the actual value |
| 83 | +ended up being. |
0 commit comments