From dc41c0e5f7458fa8b057b050c7c91f3fd083e235 Mon Sep 17 00:00:00 2001 From: Richard Nienaber Date: Mon, 7 Sep 2026 17:07:28 +0100 Subject: [PATCH] remove isRegex and close the step object at format 0.9 Redactions have superseded isRegex since 0.4: a {{name}} placeholder says which part of a line varies and why, where a whole-line regular expression made the line stop reading as the output it stands for. Keeping both meant two ways to match by pattern, a rule forbidding their combination, and a step type that could be either. Nothing has been written against isRegex, so it goes now rather than waiting for 1.0. While MAJOR is 0 a minor may take something away as well as add it, which is what 0.x means everywhere else; version.go and the format doc now say so, and the promise starts at 1.0. The step object gains additionalProperties: false, without which a script still carrying isRegex would have been accepted and quietly matched literally -- reporting success for a comparison it did not make, which is the one failure this tool must not commit itself. It is now rejected by name. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_019f9gkZVUEo3jtv51GSb4vJ --- docs/script-format.md | 23 ++++++++++++------ internal/play/play_integration_test.go | 4 ++-- internal/play/step_matcher.go | 11 ++++----- internal/play/step_matcher_test.go | 6 ++--- internal/script/redaction.go | 19 ++++++--------- internal/script/redaction_test.go | 32 +------------------------- internal/script/script.go | 3 +-- internal/script/script_parse_test.go | 23 +++++++++--------- internal/script/script_schema.json | 7 ++---- internal/script/utils.go | 7 ------ internal/script/validation.go | 21 ----------------- internal/script/version.go | 6 ++++- 12 files changed, 52 insertions(+), 110 deletions(-) diff --git a/docs/script-format.md b/docs/script-format.md index 2073017..c79610e 100644 --- a/docs/script-format.md +++ b/docs/script-format.md @@ -52,6 +52,10 @@ field names the same script would otherwise produce. ### Adding a version +While MAJOR is `0` the format is not stable, and a minor may take a field away +as well as add one -- which is what `0.x` means everywhere else, and what `0.9` +did to `isRegex`. Once `1.0` is cut, removing a field becomes a major bump. + In the same change that alters the schema: 1. Append the new version to `knownVersions`. `CurrentVersion` follows the last @@ -75,6 +79,7 @@ but means nothing is worse than no version at all. | `0.6` | Added `terminal`, and made a pty the default. | | `0.7` | Added a per-step `timeout`. | | `0.8` | A runner may use `${runnerDir}` where it names a path. | +| `0.9` | Removed `isRegex`; redactions are the only way to match by pattern. | ### Known limitation @@ -386,9 +391,9 @@ way. Normalising differently is how a comparison quietly stops comparing. ### Why not just a regular expression -`isRegex` swaps exact matching for a regular expression over the entire line. To -mask one volatile number with it you have to write a pattern for everything -around that number too: +Until `0.9` a step could set `isRegex` and match the whole line as a regular +expression. To mask one volatile number with it you had to write a pattern for +everything around that number too: ```yaml - line: '^wrote /[^ ]+ in [0-9]+ms$' @@ -398,16 +403,20 @@ around that number too: which no longer reads as the output it stands for, and no longer says which part was expected to vary or why. The version with `{{elapsed}}` says both. -`isRegex` still works. It is superseded, not removed: taking it away means every -script using one has to be rewritten, which is a major version bump. Prefer -redactions in anything written from now on. +`isRegex` was removed in `0.9`, and a step's fields are closed, so a script still +carrying one is rejected rather than quietly matched literally: + +``` +Script validation errors: +runs.0.steps.0: Additional property isRegex is not allowed +``` ### Errors A placeholder naming a redaction the script does not declare is rejected, and the message lists the ones it does declare. A redaction whose pattern does not compile is reported once, against the declaration rather than against every step -that refers to it. A step cannot be both `isRegex` and use redactions. +that refers to it. ## Runners diff --git a/internal/play/play_integration_test.go b/internal/play/play_integration_test.go index e68feff..d5f0b2d 100644 --- a/internal/play/play_integration_test.go +++ b/internal/play/play_integration_test.go @@ -84,7 +84,7 @@ func TestDoubleInput(t *testing.T) { assert.Equal(t, 0, exitCode) } -func TestDoubleInputRegex(t *testing.T) { +func TestDoubleInputRedaction(t *testing.T) { t.Parallel() config := createConfig(t, "fixtures/double_input.sh") @@ -92,7 +92,7 @@ func TestDoubleInputRegex(t *testing.T) { run := script.Run{Steps: []script.Step{ {Line: "First number: ", Input: "1"}, {Line: "Second number: ", Input: "2"}, - {Line: "Sum: \\d", LineRegex: *regex, IsRegex: true}, + {Line: "Sum: {{digit}}", LineRegex: *regex, Redacted: true}, }} exitCode := Run(config.Play, run, config.Logger) diff --git a/internal/play/step_matcher.go b/internal/play/step_matcher.go index 707dfbf..9dace6b 100644 --- a/internal/play/step_matcher.go +++ b/internal/play/step_matcher.go @@ -120,18 +120,15 @@ func (matcher *StepMatcher) FailureReport(mode FailureMode, detail string) strin var report strings.Builder fmt.Fprintf(&report, "%s: step %d of %d did not match (%s)\n\n", mode, matcher.currentStepIndex+1, len(matcher.steps), detail) - switch { - case step.Redacted: + if step.Redacted { fmt.Fprintf(&report, " expected %q (with redactions applied)\n", expected) - case step.IsRegex: - fmt.Fprintf(&report, " expected %q (regular expression)\n", expected) - default: + } else { fmt.Fprintf(&report, " expected %q\n", expected) } fmt.Fprintf(&report, " received %q\n", received) // A character-level pointer only means something when the two are meant to // be equal; against a pattern the first differing byte is noise. - if !step.UsesPattern() { + if !step.Redacted { report.WriteString(differenceMarker(expected, received, len(reportLabelIndent))) } @@ -228,7 +225,7 @@ func (matcher *StepMatcher) Match(char string) error { func (matcher *StepMatcher) matchLine(step script.Step) (bool, error) { var matched bool - if step.UsesPattern() { + if step.Redacted { matched = step.LineRegex.MatchString(matcher.currentLine) } else { matched = matcher.currentLine == step.Line diff --git a/internal/play/step_matcher_test.go b/internal/play/step_matcher_test.go index 135ea0e..579260a 100644 --- a/internal/play/step_matcher_test.go +++ b/internal/play/step_matcher_test.go @@ -86,15 +86,15 @@ func TestFailureReportOmitsMarkerWhenNothingWasReceived(t *testing.T) { assert.NotContains(t, report, "^") } -func TestFailureReportOmitsMarkerForRegexSteps(t *testing.T) { +func TestFailureReportOmitsMarkerForRedactedSteps(t *testing.T) { t.Parallel() pattern := regexp.MustCompile(`^Rolled \d+$`) - matcher := newTestMatcher([]script.Step{{Line: pattern.String(), IsRegex: true, LineRegex: *pattern}}) + matcher := newTestMatcher([]script.Step{{Line: "Rolled {{n}}", Redacted: true, LineRegex: *pattern}}) feed(t, &matcher, "Rolled twelve") report := matcher.FailureReport(NoMatch, "nothing matched it within 5s") - assert.Contains(t, report, "(regular expression)") + assert.Contains(t, report, "(with redactions applied)") // Pointing at the first byte where output differs from a pattern would be // meaningless. assert.NotContains(t, report, "first difference") diff --git a/internal/script/redaction.go b/internal/script/redaction.go index 13d5ed8..9e5432e 100644 --- a/internal/script/redaction.go +++ b/internal/script/redaction.go @@ -17,11 +17,12 @@ var redactionPlaceholder = regexp.MustCompile(`\{\{([^{}]*)\}\}`) // into a regular expression, substituting the named pattern and quoting // everything around it. // -// This is what a fixture wants instead of isRegex. Masking one volatile number -// with isRegex means hand-writing a regular expression for the whole line, at -// which point the line stops being readable as the output it stands for and -// the intent behind the mask is lost. A name keeps both: the line still looks -// like what the program prints, and {{seed}} says why that part varies. +// This is the only way a step matches by pattern. The alternative it replaced +// -- declaring the whole line to be a regular expression -- meant hand-writing +// one to mask a single volatile number, at which point the line stopped being +// readable as the output it stands for and the intent behind the mask was +// lost. A name keeps both: the line still looks like what the program prints, +// and {{seed}} says why that part varies. func compileRedactions(script Script) []string { var errors []string @@ -43,11 +44,6 @@ func compileRedactions(script Script) []string { } where := fmt.Sprintf("runs.%d.steps.%d.line", runIndex, stepIndex) - if step.IsRegex { - errors = append(errors, where+": a step cannot both be a regular expression and use redactions") - continue - } - pattern, unknown := buildPattern(step.Line, placeholders, script.Redactions, known) if len(unknown) > 0 { errors = append(errors, fmt.Sprintf("%s: %s", where, unknownRedactions(unknown, script.Redactions))) @@ -71,8 +67,7 @@ func compileRedactions(script Script) []string { } // buildPattern anchors at both ends: a redacted line stands for the whole line -// the program printed, the same as a line matched literally does. isRegex is -// unanchored and stays that way, because scripts already rely on it. +// the program printed, the same as a line matched literally does. func buildPattern(line string, placeholders [][]int, redactions map[string]string, known map[string]bool) (string, []string) { var pattern strings.Builder var unknown []string diff --git a/internal/script/redaction_test.go b/internal/script/redaction_test.go index ce82e57..ba723c7 100644 --- a/internal/script/redaction_test.go +++ b/internal/script/redaction_test.go @@ -24,7 +24,6 @@ func TestRedactionMatchesTheVaryingPart(t *testing.T) { step, err := parseWithRedactions(t, `{"rolls": "[0-9]+"}`, `" 7 {{rolls}} "`) assert.NoError(t, err) assert.True(t, step.Redacted) - assert.True(t, step.UsesPattern()) assert.True(t, step.LineRegex.MatchString(" 7 807 ")) assert.True(t, step.LineRegex.MatchString(" 7 12 ")) } @@ -60,7 +59,7 @@ func TestLineWithoutPlaceholdersStaysLiteral(t *testing.T) { step, err := parseWithRedactions(t, `{"n": "[0-9]+"}`, `"HOW MANY ROLLS? "`) assert.NoError(t, err) assert.False(t, step.Redacted) - assert.False(t, step.UsesPattern()) + assert.Empty(t, step.LineRegex.String()) } func TestUnknownRedactionIsRejected(t *testing.T) { @@ -93,19 +92,6 @@ redactions.n: error parsing regexp: missing closing ): ` + "`(unterminated`" assert.Equal(t, expected, err.Error()) } -func TestStepCannotBeBothRegexAndRedacted(t *testing.T) { - document := `{ - "version": "0.4", - "redactions": {"n": "[0-9]+"}, - "runs": [{"arguments": [], "exitCode": 0, "steps": [{"line": "seed {{n}}", "isRegex": true}]}] -}` - _, err := ParseScriptFromBytes([]byte(document)) - assert.Error(t, err) - expected := `Script validation errors: -runs.0.steps.0.line: a step cannot both be a regular expression and use redactions` - assert.Equal(t, expected, err.Error()) -} - // Redactions are declared for the script, so runs being compared normalise the // same things in the same way rather than each carrying its own copy. func TestRedactionsApplyToEveryRun(t *testing.T) { @@ -124,19 +110,3 @@ func TestRedactionsApplyToEveryRun(t *testing.T) { assert.True(t, run.Steps[0].LineRegex.MatchString("rolled 6"), run.Name) } } - -// isRegex still works. It is superseded, not removed: taking it away would -// mean rewriting every script that uses one, which is a major version bump. -func TestIsRegexStillWorks(t *testing.T) { - document := `{ - "version": "0.4", - "runs": [{"arguments": [], "exitCode": 0, "steps": [{"line": "hello \\w+", "isRegex": true}]}] -}` - script, err := ParseScriptFromBytes([]byte(document)) - assert.NoError(t, err) - - step := script.Runs[0].Steps[0] - assert.True(t, step.UsesPattern()) - assert.False(t, step.Redacted) - assert.True(t, step.LineRegex.MatchString("hello richard")) -} diff --git a/internal/script/script.go b/internal/script/script.go index 967a1ab..f1ea129 100644 --- a/internal/script/script.go +++ b/internal/script/script.go @@ -93,8 +93,7 @@ func ParseScriptFromBytes(json []byte) (Script, error) { return Script{}, err } - regexErrors = validateRegexes(script.Runs) - regexErrors = append(regexErrors, compileRedactions(script)...) + regexErrors = compileRedactions(script) regexErrors = append(regexErrors, validateTimeouts(script.Runs)...) regexErrors = append(regexErrors, ensureNames(script.Runs)...) if len(regexErrors) == 0 { diff --git a/internal/script/script_parse_test.go b/internal/script/script_parse_test.go index 0276f31..bb9c54f 100644 --- a/internal/script/script_parse_test.go +++ b/internal/script/script_parse_test.go @@ -23,8 +23,7 @@ func TestBasicScript(t *testing.T) { "line": "enter your name: ", "input": "richard" }, { - "line": "hello \\w+", - "isRegex": true + "line": "hello richard" }] }] }` @@ -45,13 +44,11 @@ func TestBasicScript(t *testing.T) { assert.Equal(t, "enter your name: ", run.Steps[0].Line) assert.Equal(t, "richard", run.Steps[0].Input) - assert.False(t, run.Steps[0].IsRegex) stepOne := run.Steps[1] - assert.Equal(t, "hello \\w+", stepOne.Line) + assert.Equal(t, "hello richard", stepOne.Line) assert.Equal(t, "", stepOne.Input) - assert.True(t, stepOne.IsRegex) - assert.True(t, stepOne.LineRegex.MatchString("hello richard")) + assert.False(t, stepOne.Redacted) } func TestGeneratesNames(t *testing.T) { @@ -95,8 +92,7 @@ func TestValidationFailsForIncorrectType(t *testing.T) { "line": "enter your name: ", "input": "richard" }, { - "line": "hello \\w+", - "isRegex": true + "line": "hello richard" }] }] }` @@ -184,16 +180,19 @@ func TestEveryKnownVersionIsReadable(t *testing.T) { } } -func TestHandlesInvalidRegex(t *testing.T) { +// isRegex was removed in 0.9, and a step's properties are closed so that a +// script still carrying one is told about it rather than quietly matched +// literally. +func TestRejectsIsRegex(t *testing.T) { basicScript := `{ - "version": "0.1", + "version": "0.9", "runs": [{ "arguments": [ "-l" ], "exitCode": 0, "steps": [{ - "line": "hello (w+", + "line": "hello \\w+", "isRegex": true }] }] @@ -201,7 +200,7 @@ func TestHandlesInvalidRegex(t *testing.T) { _, err := ParseScriptFromBytes([]byte(basicScript)) assert.Error(t, err) expected := `Script validation errors: -runs.0.steps.0.line: error parsing regexp: missing closing ): ` + "`hello (w+`" +runs.0.steps.0: Additional property isRegex is not allowed` assert.Equal(t, expected, err.Error()) } diff --git a/internal/script/script_schema.json b/internal/script/script_schema.json index 0157d40..5c28a76 100644 --- a/internal/script/script_schema.json +++ b/internal/script/script_schema.json @@ -80,12 +80,9 @@ "timeout": { "description": "How long to wait for output while this step is the one being waited for, as a Go duration such as '2m'. Replaces the run's timeout for this step only. Added in 0.7.", "type": "string" - }, - "isRegex": { - "description": "Match the whole line as a regular expression. Superseded by redactions, which keep the line readable as the output it stands for; see docs/script-format.md.", - "type": "boolean" } - } + }, + "additionalProperties": false } } }, diff --git a/internal/script/utils.go b/internal/script/utils.go index 81899ba..64502bb 100644 --- a/internal/script/utils.go +++ b/internal/script/utils.go @@ -9,7 +9,6 @@ type Step struct { Line string `json:"line"` LineRegex regexp.Regexp `json:"-"` Input string `json:"input,omitempty"` - IsRegex bool `json:"isRegex,omitempty"` // Redacted is set while parsing, for a line that referred to a redaction // and so matches by pattern rather than by equality. It is not part of the @@ -26,12 +25,6 @@ type Step struct { TimeoutDuration time.Duration `json:"-"` } -// UsesPattern reports whether the step matches by regular expression rather -// than by exact equality, whichever of the two ways it got there. -func (step Step) UsesPattern() bool { - return step.IsRegex || step.Redacted -} - type Run struct { Name string `json:"name,omitempty"` Timestamp time.Time `json:"timestamp"` diff --git a/internal/script/validation.go b/internal/script/validation.go index b496f6f..0a81235 100644 --- a/internal/script/validation.go +++ b/internal/script/validation.go @@ -3,7 +3,6 @@ package script import ( "errors" "fmt" - "regexp" "sort" "strings" "time" @@ -11,26 +10,6 @@ import ( schema "github.com/xeipuuv/gojsonschema" ) -func validateRegexes(runs []Run) []string { - var regexErrors []string - // validate regexes should they exist - for runIndex, run := range runs { - for stepIndex := range run.Steps { - step := &run.Steps[stepIndex] - if step.IsRegex { - regex, err := regexp.Compile(step.Line) - if err != nil { - regexError := fmt.Sprintf("runs.%d.steps.%d.line: %s", runIndex, stepIndex, err.Error()) - regexErrors = append(regexErrors, regexError) - } else { - step.LineRegex = *regex - } - } - } - } - return regexErrors -} - // validateTimeouts parses each step's timeout override. A duration that does // not parse is reported here rather than at play time, alongside the regexes // and for the same reason: a script that cannot be run is worth knowing about diff --git a/internal/script/version.go b/internal/script/version.go index 686a28b..23081bc 100644 --- a/internal/script/version.go +++ b/internal/script/version.go @@ -18,8 +18,12 @@ import ( // majors are dropped from this list at that point, and the error names the // last release that could read them. // +// While MAJOR is 0 the format is not stable and a minor may take something +// away as well as add it, which is what 0.x means everywhere else and what +// 0.9 did to isRegex. Once 1.0 is cut, the rule above is a promise. +// // Add a version here in the same change that alters the schema, never before. -var knownVersions = []string{"0.1", "0.2", "0.3", "0.4", "0.5", "0.6", "0.7", "0.8"} +var knownVersions = []string{"0.1", "0.2", "0.3", "0.4", "0.5", "0.6", "0.7", "0.8", "0.9"} // CurrentVersion is the version `record` writes and the newest this build // understands.