jq test() : Match a String Against a Regex
jq test(regex) returns true if the input string matches the pattern, false otherwise.
test() pairs with select() to keep API items whose name or ref matches a pattern, such as release tags or feature branches.
What it does
test(re) tests the input string against an Oniguruma regex and returns a boolean. test(re; "i") adds flags like case-insensitive. match(re) returns capture details and capture extracts named groups; test is the lightweight yes/no form for filtering.
Common usage
# keep semver-looking tags
jq '.[] | select(.name | test("^v[0-9]+\\.[0-9]+"))' tags.json
# case-insensitive branch match
jq '.[] | select(.ref | test("hotfix"; "i"))' branches.json
# gate a step on a pattern
jq -e '.ref | test("^refs/tags/")' event.jsonFunctions
| Function | What it does |
|---|---|
| test(re) | Boolean match |
| test(re; "i") | Case-insensitive match |
| match(re) | Match object with offsets and captures |
| capture(re) | Object of named captures |
In CI
Combine test with -e so a non-match exits non-zero and a workflow step can branch on the regex result without parsing output.
Common errors in CI
"jq: error: <stdin>:0: test input must be a string" means the field was not a string; coerce with tostring or guard for null. "jq: error: ... invalid regex" means an unescaped backslash; in a shell single-quoted program double the backslash for digits, as in [0-9] over \\d.