jq

The atago project wrote these specs on its own initiative and runs them in its own CI, to exercise atago against a real program. They are not jq’s official test suite, and the jq project is not affiliated with atago.

Summary #

2 suites · 11 scenarios

Contents #

jq (uncovered contracts — unicode passthrough + empty validation) #

Two guarantees the main jq suite leaves untested.

First, that jq is safe for text that is not ASCII: multibyte characters must survive a round trip byte for byte, with no re-encoding and no escaping applied on the way through.

Second, that jq empty works as the validator everyone uses it as. It consumes the document, prints nothing at all, and exits 0 — but exits 5 on malformed input. That combination (silent on success, non-zero on garbage) is what makes it usable as a JSON check in a script, and both halves are pinned here.

Source: test/e2e/thirdparty/jq/extra.atago.yaml

Scenario: multibyte unicode passes through unchanged #

Inputs #

stdin for jq:

{"s":"café 😀 日本語"}

When #

jq -c .

Then #

  • exit code is 0
  • stdout equals an exact value

Scenario: jq empty validates JSON — silent success, loud failure #

Inputs #

stdin for jq:

{"a":1,"b":[2,3]}

stdin for jq:

not json

When #

jq empty
jq empty

Then #

  • after jq empty:
    • exit code is 0
    • stdout is empty
    • stderr is empty
  • after jq empty:
    • exit code is one of 4, 5
    • stdout is empty
    • stderr contains parse error

jq (third-party CLI, no build required) #

jq is a filter: JSON in on stdin, JSON out on stdout, and an exit code that tells the calling script what happened.

That exit-code contract is unusually rich, and it is what this suite pins, because a shell pipeline depends on it: 0 when the filter ran, 1 when -e saw a false or null result, 2 for a usage or system error, 3 for a program that does not compile, and 5 when the input was not valid JSON at all. Four different kinds of “it didn’t work”, each of which a script may need to handle differently — and each of which must not be confused for the others.

Source: test/e2e/thirdparty/jq/jq.atago.yaml

Scenario: identity filter echoes the document from stdin #

Inputs #

stdin for jq:

{"b":2,"a":1}

When #

jq -c .

Then #

  • exit code is 0
  • stdout at $.a equals 1
  • stderr is empty

Scenario: sort-keys output is deterministic and exact #

Given #

  • Fixture file input.json is created.

Inputs #

Fixture input.json:

{"b":2,"a":1}

stdin for jq:

(read from file input.json)

When #

jq -c --sort-keys .

Then #

  • exit code is 0
  • stdout equals an exact value

Scenario: raw output strips JSON quoting #

Given #

  • Fixture file user.json is created.

Inputs #

Fixture user.json:

{"name":"alice","admin":true}

When #

jq -r .name user.json

Then #

  • exit code is 0
  • stdout equals an exact value

Scenario: arguments flow in with –arg #

Inputs #

stdin for jq:

null

When #

jq -c --arg who atago '{greeting: ("hello " + $who)}'

Then #

  • exit code is 0
  • stdout at $.greeting equals hello atago

Scenario: reduce aggregates an array #

Given #

  • Fixture file nums.json is created.

Inputs #

Fixture nums.json:

[1,2,3,4,5]

When #

jq 'reduce .[] as $n (0; . + $n)' nums.json

Then #

  • exit code is 0
  • stdout equals an exact value

Scenario: -e exits 1 when the result is false #

Inputs #

stdin for jq:

{"present":1}

When #

jq -e '.missing'

Then #

  • exit code is 1

Scenario: a program that does not compile exits 3 with a diagnostic on stderr #

Inputs #

stdin for jq:

{}

When #

jq '.foo['

Then #

  • exit code is 3
  • stdout is empty
  • stderr contains error

Scenario: invalid JSON input fails loudly and keeps stdout clean #

Inputs #

stdin for jq:

not json at all

When #

jq .

Then #

  • exit code is not 0
  • stderr contains parse error

Scenario: streaming several documents produces one result per document #

Inputs #

stdin for jq:

{"n":1}
{"n":2}

When #

jq -c '.n * 2'

Then #

  • exit code is 0
  • stdout line 1 equals an exact value
  • stdout line 2 equals an exact value