diff options
Diffstat (limited to 'tools/build_defs/jsonnet/README.md')
| -rw-r--r-- | tools/build_defs/jsonnet/README.md | 212 |
1 files changed, 209 insertions, 3 deletions
diff --git a/tools/build_defs/jsonnet/README.md b/tools/build_defs/jsonnet/README.md index 32865a87ec..7d28f15133 100644 --- a/tools/build_defs/jsonnet/README.md +++ b/tools/build_defs/jsonnet/README.md @@ -4,6 +4,7 @@ * [`jsonnet_library`](#jsonnet_library) * [`jsonnet_to_json`](#jsonnet_to_json) +* [`jsonnet_to_json_test`](#jsonnet_to_json_test) ## Overview @@ -79,9 +80,9 @@ Suppose you have the following directory structure: [workspace]/ WORKSPACE configs/ - BUILD - backend.jsonnet - frontend.jsonnet + BUILD + backend.jsonnet + frontend.jsonnet ``` You can use the `jsonnet_library` rule to build a collection of `.jsonnet` @@ -327,3 +328,208 @@ jsonnet_to_json( ``` [multiple-output-files]: http://google.github.io/jsonnet/doc/commandline.html + +<a name="#jsonnet_to_json_test"></a> +## jsonnet_to_json_test + +```python +jsonnet_to_json_test(name, src, deps, imports, golden, error=0, regex=False) +``` + +<table> + <thead> + <tr> + <th>Attribute</th> + <th>Description</th> + </tr> + </thead> + <tbody> + <tr> + <td><code>name</code></td> + <td> + <code>Name, required</code> + <p>A unique name for this rule.</p> + <p> + This name will be used as the name of the JSON file generated by this + rule. + </p> + </td> + </tr> + <tr> + <td><code>src</code></td> + <td> + <code>Label, required</code> + <p> + The <code>.jsonnet</code> file to convert to JSON. + </p> + </td> + </tr> + <tr> + <td><code>deps</code></td> + <td> + <code>List of labels, optional</code> + <p> + List of targets that are required by the <code>src</code> Jsonnet + file. + </p> + </td> + </tr> + <tr> + <td><code>imports</code></td> + <td> + <code>List of strings, optional</code> + <p> + List of import <code>-J</code> flags to be passed to the + <code>jsonnet</code> compiler. + </p> + </td> + </tr> + <tr> + <td><code>vars</code></td> + <td> + <code>String dict, optional</code> + <p> + Map of variables to pass to jsonnet via <code>--var key=value</code>. + </p> + </td> + </tr> + <tr> + <td><code>code_vars</code></td> + <td> + <code>String dict, optional</code> + <p> + Map of code variables to pass to jsonnet via + <code>--code-var key=value</code>. + </p> + </td> + </tr> + <tr> + <td><code>golden</code></td> + <td> + <code>Label, optional</code> + <p> + The expected (combined stdout and stderr) output to compare to the + output of running <code>jsonnet</code> on <code>src</code>. + </p> + </td> + </tr> + <tr> + <td><code>error</code></td> + <td> + <code>Integer, optional, default is 0</code> + <p> + The expected error code from running <code>jsonnet</code> on + <code>src</code>. + </p> + </td> + </tr> + <tr> + <td><code>regex</code></td> + <td> + <code>bool, optional, default is False</code> + <p> + Set to 1 if <code>golden</code> contains a regex used to match + the output of running <code>jsonnet</code> on <code>src</code>. + </p> + </td> + </tr> + </tbody> +</table> + +### Example + +Suppose you have the following directory structure: + +``` +[workspace]/ + WORKSPACE + config/ + BUILD + base_config.jsonnet + test_config.jsonnet + test_config.json +``` + +Suppose that `base_config.jsonnet` is a library Jsonnet file, containing the +base configuration for a service. Suppose that `test_config.jsonnet` is a test +configuration file that is used to test `base_config.jsonnet`, and +`test_config.json` is the expected JSON output from compiling +`test_config.jsonnet`. + +The `jsonnet_to_json_test` rule can be used to verify that compiling a Jsonnet +file produces the expected JSON output. Simply define a `jsonnet_to_json_test` +target and provide the input test Jsonnet file and the `golden` file containing +the expected JSON output: + +`config/BUILD`: + +```python +load( + "/tools/build_defs/jsonnet/jsonnet", + "jsonnet_library", + "jsonnet_to_json_test", +) + +jsonnet_library( + name = "base_config", + srcs = ["base_config.jsonnet"], +) + +jsonnet_to_json_test( + name = "test_config_test", + src = "test_config", + deps = [":base_config"], + golden = "test_config.json", +) +``` + +To run the test: `bazel test //config:test_config_test` + +### Example: Negative tests + +Suppose you have the following directory structure: + +``` +[workspace]/ + WORKSPACE + config/ + BUILD + base_config.jsonnet + invalid_config.jsonnet + invalid_config.output +``` + +Suppose that `invalid_config.jsonnet` is a Jsonnet file used to verify that +an invalid config triggers an assertion in `base_config.jsonnet`, and +`invalid_config.output` is the expected error output. + +The `jsonnet_to_json_test` rule can be used to verify that compiling a Jsonnet +file results in an expected error code and error output. Simply define a +`jsonnet_to_json_test` target and provide the input test Jsonnet file, the +expected error code in the `error` attribute, and the `golden` file containing +the expected error output: + +`config/BUILD`: + +```python +load( + "/tools/build_defs/jsonnet/jsonnet", + "jsonnet_library", + "jsonnet_to_json_test", +) + +jsonnet_library( + name = "base_config", + srcs = ["base_config.jsonnet"], +) + +jsonnet_to_json_test( + name = "invalid_config_test", + src = "invalid_config", + deps = [":base_config"], + golden = "invalid_config.output", + error = 1, +) +``` + +To run the test: `bazel test //config:invalid_config_test` |