jsonnet-tool is a simple binary, primarily used to build YAML configuration files from Jsonnet source configurations.

$ cat file.jsonnet
{
  'file.yaml': std.manifestYamlDoc({
    hello: true,
    there: 1,
    moo: {
      there: 1,
      hello: true,
    },
  }),
}
$ jsonnet-tool yaml \
    --multi "./output" \ #       - Directory to emit the YAML file to
    --header "# DO NOT EDIT" \ # - Header to prefix to output YAML
    -J "./libsonnet/" \ #        - Jsonnet Import Search Path
    -J "./vendor/" \ #           - .. supports multiple
    -P name \ #                  - Keys to appear at the top of YAML
    -P alert \ #                 - .. supports multiple
    --prefix "autogenerated-" \  - Prefix added to file names
    file.jsonnet

Render is a generic rendering utility for jsonnet. In the case of JSON and YAML, the output does not need to be manifested, the tool will use the extension of the file to appropriately manifest the output.

$ cat file.jsonnet
{
  // File will contain YAML output
  'file.yaml': {
    hello: true,
    there: 1,
    moo: {
      there: 1,
      hello: true,
    },
  },

  // Subdirectories are automatically created
  'x/y/z/file.json': {
    hello: 1,
    x: [1, 2, 3],
  },
}
$ jsonnet-tool render \
    --multi "./output" \ #       - Directory to emit the YAML file to
    -J "./libsonnet/" \ #        - Jsonnet Import Search Path
    -J "./vendor/" \ #           - .. supports multiple
    --prefix "autogenerated-" \  - Prefix added to file names
    file.jsonnet

This tool allows for Jsonnet manifested output to be tested against fixture files.

The term "manitest" is a portmanteau of "manifest" and "test".

Each test case is kept in a file with the .manitest.jsonnet suffix.

{
  // Test case using a JSON fixture
  testcase1: function() {
    actual: a_function_being_tested(),

    // Compare the output of actual to the JSON
    // in the named file...
    expectJSON: './fixtures/test1.testcase1.json',
  },

  // Test case using a YAML fixture
  testcase2: function() {
    actual: std.manifestYamlDoc({ hello: 'world' }),

    // Compare the output of actual to the YAML
    // in the named file...
    expectYAML: './fixtures/test1.testcase2.yaml',
  },

  // Test case using a plain text fixture
  testcase3: function() {
    actual: generateIniFile(),

    // Compare the output of actual to the text
    // in the named file...
    expectPlainText: './fixtures/test1.testcase2.ini',
  },

  // No fixtures...
  testcase4: function() {
    actual: { hello: world },

    // Compare the output of actual to the JSON value
    expect: { hello: world },
  },
}

At present, four types of expectation matchers are available:

1. expectJSON will match the actual value against a JSON fixture file.
2. expectYAML will match the actual value against a YAML fixture file.
3. expectPlainText will match the actual value against a plain text fixture file.
4. expect will match the actual value against arbitrary JSON without using a fixture file. Unless the expectation is trivial, this match should be avoided.

$ cat examples/tests/test1.manitest.jsonnet
{ ... }
$ jsonnet-tool test examples/tests/test1.manitest.jsonnet
▶️  Executing manitest examples/tests/test1.manitest.jsonnet
  ✔️  testcase1
  ✔️  testcase2
  Completed examples/tests/test1.manitest.jsonnet

Jsonnet test performance can be greatly improved by caching results. The jsonnet-tool test harness will analyze which files and fixtures, including all dependencies imported via import, importstr, importbin etc and, if the none of the files have changes, skip them from the test run.

Since jsonnet is hermetic, meaning that the output is always the same if the input and files are the same, this is a safe operation.

Caching can be enabled with the --cache flag.

$ time jsonnet-tool test --cache examples/tests/test1.manitest.jsonnet
▶️  Executing manitest examples/tests/test1.manitest.jsonnet
  ✔️  examples/tests/test1.manitest.jsonnet (all tests) (cached)
  Completed examples/tests/test1.manitest.jsonnet
./jsonnet-tool test examples/tests/test1.manitest.jsonnet --cache  0.00s user 0.01s system 2% cpu 0.593 total

jsonnet-tool test will include color-coded diff comparing the actual and expected values.

$ jsonnet-tool test  examples/tests/test1.manitest.jsonnet
▶️  Executing manitest examples/tests/test2.manitest.jsonnet
  ❌  testcase1 failed      examples/tests/fixtures/test1.testcase1.json
    {
      "bad": "field",
      "hello": "world"
    }

  ✔️  testcase2
  Failed examples/tests/test2.manitest.jsonnet 2 test(s) completed with 1 failure(s)

When performing large refactors, it can sometimes be preferable to simply rewrite all fixtures and carefully review the changes instead of manually updating each fixture.

jsonnet-tool test can perform this, using the --write-fixtures option.

$ jsonnet-tool test  examples/tests/test1.manitest.jsonnet --write-fixtures
▶️  Executing manitest examples/tests/test1.manitest.jsonnet
  ✔️  testcase1
  ✔️  testcase2
  Completed examples/tests/test1.manitest.jsonnet
$ git diff
# compare output and, if correct, commit the change

Check the examples/ directory for examples of files suitable for jsonnet-tool.

Please create new issues in the public infrastructure project and not in this private issue tracker.

CONTRIBUTING.md is important, do not skip reading this.