diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..d94df6d --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,53 @@ +# Copyright (c) the go-webengine/webtest authors. +# SPDX-License-Identifier: BSD-3-Clause +name: CI + +on: + push: + branches: [main] + pull_request: + branches: [main] + workflow_dispatch: + +permissions: + contents: read + +env: + GO_VERSION: "1.27.3" + +jobs: + test: + name: build · vet · gofmt · test · govulncheck + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + + - uses: actions/setup-go@v7 + with: + go-version: ${{ env.GO_VERSION }} + check-latest: true + + - name: Build + run: go build ./... + + - name: Vet + run: go vet ./... + + - name: gofmt + run: | + unformatted=$(gofmt -l .) + if [ -n "$unformatted" ]; then + echo "$unformatted" + exit 1 + fi + + - name: Test + run: go test ./... + + - name: Race + run: go test -race ./... + + - name: govulncheck + run: | + go install golang.org/x/vuln/cmd/govulncheck@latest + govulncheck ./... diff --git a/README.md b/README.md index db1e15e..d185e8d 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,56 @@ # webtest -HCL-driven browser-automation CLI for go-webengine/engine (click/fill-form/assert test scenarios) + +HCL-driven browser-automation CLI for [go-webengine/engine](https://github.com/go-webengine/engine): click/fill-form/assert test scenarios, for driving a rendered page's own `LiveDocument` (`Focus`/`Type`/`Click`/`Submit`) from a declarative scenario file instead of hand-written Go. + +Status: in progress. This repository currently holds only the scenario +format (`hclscenario`) — parsing, validation, and the function allowlist. +The driver/CLI wiring and the dry-run/session/pin/audit-log/anti-bot +guardrails are tracked separately and not implemented yet. + +## Scenario format + +HCL was chosen specifically for its native function-call expressions — an +escape valve for logic beyond pure declarative description, without going +all the way to embedding real Go/script code in a scenario file. + +```hcl +scenario "login" { + url = "https://example.com/login" + + pin { + selectors = ["#login-form", "#username"] + } + + step "fill" { + selector = "#username" + value = "alice" + } + step "fill" { + selector = "#password" + value = "s3cr3t" + } + step "click" { + selector = "#submit" + } + step "assert" { + selector = "#welcome" + text = "Welcome, alice" + } + step "submit" { + selector = "#login-form" + } +} +``` + +- `pin` is the pinned-page identity check: before the first step runs, the + rendered page's URL (after redirects) and every selector here must be + present, or the run refuses with a named diff rather than acting against + an unexpected page. +- `step "submit"` always computes a dry-run preview (method, URL, body) by + default; only the CLI's own `--submit` flag (once the CLI exists) makes + it a real request. +- Every attribute value is an HCL expression and may call a function from + a small, fixed, reviewed allowlist (`hclscenario.Functions`) — currently + `upper`/`lower`/`trim`/`join`. The allowlist is deliberately NOT cty's + own stdlib: no file/exec/network/env functions, nothing unbounded. See + `hclscenario/functions.go`'s own doc comment for the full rationale. diff --git a/go.mod b/go.mod new file mode 100644 index 0000000..ab855df --- /dev/null +++ b/go.mod @@ -0,0 +1,21 @@ +module github.com/go-webengine/webtest + +go 1.27.3 + +require ( + github.com/hashicorp/hcl/v2 v2.25.0 + github.com/zclconf/go-cty v1.19.0 +) + +require ( + github.com/agext/levenshtein v1.2.1 // indirect + github.com/apparentlymart/go-textseg/v15 v15.0.0 // indirect + github.com/apparentlymart/go-textseg/v17 v17.0.1 // indirect + github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect + github.com/google/go-cmp v0.7.0 // indirect + github.com/mitchellh/go-wordwrap v1.0.1 // indirect + golang.org/x/mod v0.41.0 // indirect + golang.org/x/sync v0.24.0 // indirect + golang.org/x/text v0.43.0 // indirect + golang.org/x/tools v0.51.0 // indirect +) diff --git a/go.sum b/go.sum new file mode 100644 index 0000000..649693a --- /dev/null +++ b/go.sum @@ -0,0 +1,28 @@ +github.com/agext/levenshtein v1.2.1 h1:QmvMAjj2aEICytGiWzmxoE0x2KZvE0fvmqMOfy2tjT8= +github.com/agext/levenshtein v1.2.1/go.mod h1:JEDfjyjHDjOF/1e4FlBE/PkbqA9OfWu2ki2W0IB5558= +github.com/apparentlymart/go-textseg/v15 v15.0.0 h1:uYvfpb3DyLSCGWnctWKGj857c6ew1u1fNQOlOtuGxQY= +github.com/apparentlymart/go-textseg/v15 v15.0.0/go.mod h1:K8XmNZdhEBkdlyDdvbmmsvpAG721bKi0joRfFdHIWJ4= +github.com/apparentlymart/go-textseg/v17 v17.0.1 h1:bpMXRgQ5cEoRNuQke1a80/Nl6w3G5eoIbWo9f3gXkAs= +github.com/apparentlymart/go-textseg/v17 v17.0.1/go.mod h1:fa8X4jgGeevslICIY6LcdjkSecWnXmYd9Lk34z/VxZs= +github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM= +github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= +github.com/go-test/deep v1.0.3 h1:ZrJSEWsXzPOxaZnFteGEfooLba+ju3FYIbOrS+rQd68= +github.com/go-test/deep v1.0.3/go.mod h1:wGDj63lr65AM2AQyKZd/NYHGb0R+1RLqB8NKt3aSFNA= +github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8= +github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU= +github.com/hashicorp/hcl/v2 v2.25.0 h1:HmmQVYRny4MaBo4b20TjmL46wyuUxpnMWkPZ4+NTbWk= +github.com/hashicorp/hcl/v2 v2.25.0/go.mod h1:vR+FKETxoZAmRlHgFfKmuqivj+C4Izm/c66XkmZ3r7M= +github.com/mitchellh/go-wordwrap v1.0.1 h1:TLuKupo69TCn6TQSyGxwI1EblZZEsQ0vMlAFQflz0v0= +github.com/mitchellh/go-wordwrap v1.0.1/go.mod h1:R62XHJLzvMFRBbcrT7m7WgmE1eOyTSsCt+hzestvNj0= +github.com/zclconf/go-cty v1.19.0 h1:IV8WdqYZc2c5rLX9bEoLNXKojBAp0MZPBHMIrCoa/s4= +github.com/zclconf/go-cty v1.19.0/go.mod h1:12W89jGn3JCOIQi7infWr9m80rOkb5RNYJqXMZcN4c8= +github.com/zclconf/go-cty-debug v0.0.0-20240509010212-0d6042c53940 h1:4r45xpDWB6ZMSMNJFMOjqrGHynW3DIBuR2H9j0ug+Mo= +github.com/zclconf/go-cty-debug v0.0.0-20240509010212-0d6042c53940/go.mod h1:CmBdvvj3nqzfzJ6nTCIwDTPZ56aVGvDrmztiO5g3qrM= +golang.org/x/mod v0.41.0 h1:qJmnOUb4YB+FsEuM3HcWucdZASCPGhsX6uljO6pog0c= +golang.org/x/mod v0.41.0/go.mod h1:Ek9pY8RKWXwsWvd3rQiHYtMqkjSUV+s1Rj7j4H5Ur6o= +golang.org/x/sync v0.24.0 h1:iqiDrGoDgyuvAKrhLQthUEzU/R378N78gXbBjxed7oA= +golang.org/x/sync v0.24.0/go.mod h1:sUUOizhqBxiL6pEWpqNLUiaJn1ShEbZ6BBqskPbjZm0= +golang.org/x/text v0.43.0 h1:1QivrlhwAsnMOcqgOdl9my7s9OyZl8O5/UGUTJVXoWc= +golang.org/x/text v0.43.0/go.mod h1:hbSIYA/amXcRXTFSZqh8tWHEoqRvvbKPJ2uz/KU+a+s= +golang.org/x/tools v0.51.0 h1:k4Xc/1Om9jwkBJBo4NVLMSARBoWtK10mx+W5BnXCeAI= +golang.org/x/tools v0.51.0/go.mod h1:9eEncMayCV6zRMGhR5eZEC2iBx98qWcF1HZ9Z7wJOoA= diff --git a/hclscenario/functions.go b/hclscenario/functions.go new file mode 100644 index 0000000..ccb4923 --- /dev/null +++ b/hclscenario/functions.go @@ -0,0 +1,78 @@ +// Copyright (c) the go-webengine/webtest authors. +// SPDX-License-Identifier: BSD-3-Clause + +// Package hclscenario parses and validates an HCL scenario file: a +// declarative sequence of browser-automation steps (click/fill/assert/ +// submit) for go-webengine/engine's LiveDocument driver. +// +// HCL was chosen specifically for its native function-call expressions — an +// escape valve for logic beyond pure declarative description, without going +// all the way to embedding real Go/script code in a scenario file. That +// escape valve is also the real attack surface a scenario author's own +// expressions can reach: Functions (this file) is therefore a small, FIXED, +// reviewed allowlist, not cty's own stdlib wholesale. Every function here is +// pure (same output for the same input, no I/O, no observable side effect — +// cty's own function.Spec.Impl doc comment requires this), and explicitly +// excludes anything that could read a file, run a process, touch the +// network, or read an environment variable. None of them can make a +// scenario's own evaluation cost unbounded either: every one operates on +// its own arguments only, with no recursion or looping construct of its own +// (HCL itself gives a scenario author no way to DEFINE a new function, only +// call one of these, so the whole risk lives in exactly this list). +package hclscenario + +import ( + "strings" + + "github.com/zclconf/go-cty/cty" + "github.com/zclconf/go-cty/cty/function" +) + +// Functions is the function allowlist passed to every scenario's own +// hcl.EvalContext — the complete set a scenario's expressions may call. +func Functions() map[string]function.Function { + return map[string]function.Function{ + "upper": unaryStringFn("upper", "Returns a copy of the given string with all letters converted to upper case.", strings.ToUpper), + "lower": unaryStringFn("lower", "Returns a copy of the given string with all letters converted to lower case.", strings.ToLower), + "trim": unaryStringFn("trim", "Returns a copy of the given string with leading and trailing whitespace removed.", strings.TrimSpace), + "join": joinFn, + } +} + +// unaryStringFn builds a function.Function taking one string argument and +// returning one string, for the common case (upper/lower/trim above) — a +// single reviewed shape every new string helper reuses instead of each +// hand-rolling its own Spec. +func unaryStringFn(name, description string, impl func(string) string) function.Function { + return function.New(&function.Spec{ + Description: description, + Params: []function.Parameter{ + {Name: "s", Type: cty.String}, + }, + Type: function.StaticReturnType(cty.String), + Impl: func(args []cty.Value, retType cty.Type) (cty.Value, error) { + return cty.StringVal(impl(args[0].AsString())), nil + }, + }) +} + +// joinFn is "join(separator, list_of_strings)" — the one function here +// taking more than a single scalar, needed to build a composite value (a +// full name, a delimited path) from parts a scenario's own attributes +// already carry as separate strings. +var joinFn = function.New(&function.Spec{ + Description: "Joins the given list of strings with the given separator.", + Params: []function.Parameter{ + {Name: "separator", Type: cty.String}, + }, + VarParam: &function.Parameter{Name: "strings", Type: cty.String}, + Type: function.StaticReturnType(cty.String), + Impl: func(args []cty.Value, retType cty.Type) (cty.Value, error) { + sep := args[0].AsString() + parts := make([]string, 0, len(args)-1) + for _, a := range args[1:] { + parts = append(parts, a.AsString()) + } + return cty.StringVal(strings.Join(parts, sep)), nil + }, +}) diff --git a/hclscenario/functions_test.go b/hclscenario/functions_test.go new file mode 100644 index 0000000..0bff6b4 --- /dev/null +++ b/hclscenario/functions_test.go @@ -0,0 +1,71 @@ +// Copyright (c) the go-webengine/webtest authors. +// SPDX-License-Identifier: BSD-3-Clause + +package hclscenario + +import ( + "testing" + + "github.com/zclconf/go-cty/cty" +) + +func callString(t *testing.T, name string, args ...cty.Value) string { + t.Helper() + fn, ok := Functions()[name] + if !ok { + t.Fatalf("no such function: %s", name) + } + got, err := fn.Call(args) + if err != nil { + t.Fatalf("%s%v: %v", name, args, err) + } + return got.AsString() +} + +func TestUpper(t *testing.T) { + if got := callString(t, "upper", cty.StringVal("Alice")); got != "ALICE" { + t.Fatalf("upper(Alice) = %q, want ALICE", got) + } +} + +func TestLower(t *testing.T) { + if got := callString(t, "lower", cty.StringVal("Alice")); got != "alice" { + t.Fatalf("lower(Alice) = %q, want alice", got) + } +} + +func TestTrim(t *testing.T) { + if got := callString(t, "trim", cty.StringVal(" alice ")); got != "alice" { + t.Fatalf("trim = %q, want %q", got, "alice") + } +} + +func TestJoin(t *testing.T) { + if got := callString(t, "join", cty.StringVal("-"), cty.StringVal("a"), cty.StringVal("b"), cty.StringVal("c")); got != "a-b-c" { + t.Fatalf("join = %q, want %q", got, "a-b-c") + } +} + +func TestJoinNoParts(t *testing.T) { + if got := callString(t, "join", cty.StringVal(",")); got != "" { + t.Fatalf("join(\",\") with no parts = %q, want empty", got) + } +} + +// TestFunctionsAllowlistIsExactlyThis guards against silently growing the +// allowlist (e.g. a future contributor importing cty's own stdlib wholesale +// instead of adding one reviewed function at a time) — go-wasmcontainers' +// own security note: the function allowlist IS the attack surface, keep it +// small and reviewed. +func TestFunctionsAllowlistIsExactlyThis(t *testing.T) { + want := map[string]bool{"upper": true, "lower": true, "trim": true, "join": true} + got := Functions() + if len(got) != len(want) { + t.Fatalf("Functions() has %d entries, want exactly %d: %v", len(got), len(want), got) + } + for name := range got { + if !want[name] { + t.Fatalf("Functions() has unexpected entry %q — review before adding to the allowlist", name) + } + } +} diff --git a/hclscenario/fuzz_test.go b/hclscenario/fuzz_test.go new file mode 100644 index 0000000..994e640 --- /dev/null +++ b/hclscenario/fuzz_test.go @@ -0,0 +1,35 @@ +// Copyright (c) the go-webengine/webtest authors. +// SPDX-License-Identifier: BSD-3-Clause + +package hclscenario + +import "testing" + +// FuzzParseScenario feeds arbitrary bytes as scenario source through Parse +// — untrusted input (a scenario file is, in practice, handed around and +// edited by whoever runs these tests), exactly the kind of parser/ +// validator CLAUDE.md's own "fuzz every parser/decoder" rule targets, and +// specifically what go-wasmcontainers asked for once HCL was chosen (the +// function allowlist is the attack surface; this is the OTHER half, the +// parser/validator itself never panicking on malformed input). The only +// invariant held here is "never panics" — a malformed scenario is expected +// to be a clean, non-empty hcl.Diagnostics, not success. +func FuzzParseScenario(f *testing.F) { + seeds := []string{ + validScenario, + ``, + `scenario`, + `scenario "s" { url = "https://x/" step "fill" { selector = "#a" value = reverse("x") } }`, + `scenario "s" { url = ((((((((((1))))))))))`, + `scenario "s" "t" { url = "x" }`, + `scenario "s" { url = "x" pin { selectors = [1, 2, 3] } }`, + `scenario "s" { url = "x" step "fill" { selector = "#a" value = join(",", "a", "b") } }`, + string([]byte{0, 1, 2, 0xff, 0xfe}), + } + for _, s := range seeds { + f.Add(s) + } + f.Fuzz(func(t *testing.T, src string) { + _, _ = Parse([]byte(src), "fuzz.hcl") + }) +} diff --git a/hclscenario/schema.go b/hclscenario/schema.go new file mode 100644 index 0000000..4858ca4 --- /dev/null +++ b/hclscenario/schema.go @@ -0,0 +1,315 @@ +// Copyright (c) the go-webengine/webtest authors. +// SPDX-License-Identifier: BSD-3-Clause + +package hclscenario + +import ( + "fmt" + + "github.com/hashicorp/hcl/v2" + "github.com/hashicorp/hcl/v2/hclsyntax" + "github.com/zclconf/go-cty/cty" +) + +// evalString evaluates expr and requires the result to be a known, +// non-null string — never calls cty.Value.AsString on a value of any +// other type, which panics (confirmed directly: FuzzParseScenario's own +// first real run found this crash immediately, e.g. a scenario writing +// `url = 123`, a bare number, where a string was expected). A malformed +// scenario gets a clean diagnostic here, never a panic. +func evalString(expr hcl.Expression, ctx *hcl.EvalContext) (string, hcl.Diagnostics) { + v, diags := expr.Value(ctx) + if diags.HasErrors() { + return "", diags + } + if !v.IsKnown() { + return "", hcl.Diagnostics{{ + Severity: hcl.DiagError, + Summary: "Value must be known", + Detail: "this expression must evaluate to a known value at parse time.", + Subject: expr.Range().Ptr(), + }} + } + if v.IsNull() { + return "", hcl.Diagnostics{{ + Severity: hcl.DiagError, + Summary: "Value must not be null", + Subject: expr.Range().Ptr(), + }} + } + if v.Type() != cty.String { + return "", hcl.Diagnostics{{ + Severity: hcl.DiagError, + Summary: "Value must be a string", + Detail: fmt.Sprintf("got %s.", v.Type().FriendlyName()), + Subject: expr.Range().Ptr(), + }} + } + return v.AsString(), nil +} + +// Scenario is one parsed, validated automation scenario — a single file's +// worth. The grammar: +// +// scenario "name" { +// url = "https://example.com/login" +// +// pin { +// url = "https://example.com/login" # optional, defaults to url above +// selectors = ["#login-form", "#username"] +// } +// +// step "fill" { selector = "#username" value = "alice" } +// step "click" { selector = "#submit" } +// step "assert" { selector = "#welcome" text = "Welcome, alice" } +// step "submit" { selector = "#login-form" } +// } +// +// A scenario's expressions (any attribute value above) may call the +// functions in Functions — nothing else: no variables are defined, so a +// bare identifier other than a registered function name is a validation +// error, not a silent null. +type Scenario struct { + Name string + URL string + Pin *Pin + Steps []Step +} + +// Pin is the scenario's own pinned-page identity check: before the first +// step runs, the rendered page's URL (after redirects) and every selector +// here must be present, or the run refuses with a named diff rather than +// acting against an unexpected page. Nil if the scenario declares no pin +// block (a caller may still choose to require one). +type Pin struct { + URL string + Selectors []string +} + +// StepKind enumerates the only step types a scenario may declare. +type StepKind string + +const ( + StepClick StepKind = "click" + StepFill StepKind = "fill" + StepAssert StepKind = "assert" + StepSubmit StepKind = "submit" +) + +// Step is one scenario step, in document order. Which fields are populated +// depends on Kind: Click/Submit use only Selector; Fill uses Selector and +// Value; Assert uses Selector and, optionally, Text (empty Text means +// "assert the selector matches at least one element", not "assert empty +// text" — a scenario wanting to assert genuinely empty text is not +// distinguishable from "no text check" in this version; documented, not +// silently wrong). +type Step struct { + Kind StepKind + Selector string + Value string + Text string + HasText bool + Range hcl.Range +} + +var fileSchema = &hcl.BodySchema{ + Blocks: []hcl.BlockHeaderSchema{ + {Type: "scenario", LabelNames: []string{"name"}}, + }, +} + +var scenarioSchema = &hcl.BodySchema{ + Attributes: []hcl.AttributeSchema{ + {Name: "url", Required: true}, + }, + Blocks: []hcl.BlockHeaderSchema{ + {Type: "pin"}, + {Type: "step", LabelNames: []string{"kind"}}, + }, +} + +var pinSchema = &hcl.BodySchema{ + Attributes: []hcl.AttributeSchema{ + {Name: "url", Required: false}, + {Name: "selectors", Required: true}, + }, +} + +func stepSchema(kind StepKind) *hcl.BodySchema { + switch kind { + case StepClick, StepSubmit: + return &hcl.BodySchema{Attributes: []hcl.AttributeSchema{{Name: "selector", Required: true}}} + case StepFill: + return &hcl.BodySchema{Attributes: []hcl.AttributeSchema{ + {Name: "selector", Required: true}, + {Name: "value", Required: true}, + }} + case StepAssert: + return &hcl.BodySchema{Attributes: []hcl.AttributeSchema{ + {Name: "selector", Required: true}, + {Name: "text", Required: false}, + }} + default: + return &hcl.BodySchema{} + } +} + +// Parse parses and fully validates src as a scenario file. Diagnostics is +// non-empty (HasErrors true) for anything from a syntax error to an +// unregistered function call to a step of an unrecognized kind — Parse +// never panics on malformed input (see FuzzParseScenario) and never +// guesses a missing/ambiguous value. +func Parse(src []byte, filename string) (*Scenario, hcl.Diagnostics) { + f, diags := hclsyntax.ParseConfig(src, filename, hcl.InitialPos) + if diags.HasErrors() { + return nil, diags + } + + fc, fdiags := f.Body.Content(fileSchema) + diags = diags.Extend(fdiags) + if diags.HasErrors() { + return nil, diags + } + scenarios := fc.Blocks.OfType("scenario") + if len(scenarios) != 1 { + diags = diags.Append(&hcl.Diagnostic{ + Severity: hcl.DiagError, + Summary: "Exactly one scenario block is required", + Detail: fmt.Sprintf("found %d scenario blocks; a scenario file holds exactly one.", len(scenarios)), + Subject: &f.Body.(*hclsyntax.Body).SrcRange, + }) + return nil, diags + } + sb := scenarios[0] + + sc := &Scenario{Name: sb.Labels[0]} + ctx := &hcl.EvalContext{Functions: Functions()} + + content, cdiags := sb.Body.Content(scenarioSchema) + diags = diags.Extend(cdiags) + if diags.HasErrors() { + return nil, diags + } + + if attr, ok := content.Attributes["url"]; ok { + v, vdiags := evalString(attr.Expr, ctx) + diags = diags.Extend(vdiags) + sc.URL = v + } + + for _, b := range content.Blocks.OfType("pin") { + pin, pdiags := parsePin(b, ctx) + diags = diags.Extend(pdiags) + sc.Pin = pin + } + if len(content.Blocks.OfType("pin")) > 1 { + diags = diags.Append(&hcl.Diagnostic{ + Severity: hcl.DiagError, + Summary: "Only one pin block is allowed", + Subject: &content.Blocks.OfType("pin")[1].DefRange, + }) + } + + for _, b := range content.Blocks.OfType("step") { + step, sdiags := parseStep(b, ctx) + diags = diags.Extend(sdiags) + if !sdiags.HasErrors() { + sc.Steps = append(sc.Steps, step) + } + } + + if diags.HasErrors() { + return nil, diags + } + return sc, diags +} + +func parsePin(b *hcl.Block, ctx *hcl.EvalContext) (*Pin, hcl.Diagnostics) { + content, diags := b.Body.Content(pinSchema) + if diags.HasErrors() { + return nil, diags + } + pin := &Pin{} + if attr, ok := content.Attributes["url"]; ok { + v, vdiags := evalString(attr.Expr, ctx) + diags = diags.Extend(vdiags) + pin.URL = v + } + if attr, ok := content.Attributes["selectors"]; ok { + v, vdiags := attr.Expr.Value(ctx) + diags = diags.Extend(vdiags) + if !vdiags.HasErrors() { + if v.IsNull() || !v.IsKnown() || !v.CanIterateElements() { + diags = diags.Append(&hcl.Diagnostic{ + Severity: hcl.DiagError, + Summary: "selectors must be a list of strings", + Subject: attr.Expr.Range().Ptr(), + }) + } else { + for it := v.ElementIterator(); it.Next(); { + _, ev := it.Element() + if ev.IsNull() || !ev.IsKnown() || ev.Type() != cty.String { + diags = diags.Append(&hcl.Diagnostic{ + Severity: hcl.DiagError, + Summary: "selectors must be a list of strings", + Detail: "every element must be a known, non-null string.", + Subject: attr.Expr.Range().Ptr(), + }) + continue + } + pin.Selectors = append(pin.Selectors, ev.AsString()) + } + } + } + } + if len(pin.Selectors) == 0 && !diags.HasErrors() { + diags = diags.Append(&hcl.Diagnostic{ + Severity: hcl.DiagError, + Summary: "pin.selectors must have at least one selector", + Subject: &b.DefRange, + }) + } + return pin, diags +} + +func parseStep(b *hcl.Block, ctx *hcl.EvalContext) (Step, hcl.Diagnostics) { + kind := StepKind(b.Labels[0]) + step := Step{Kind: kind, Range: b.DefRange} + switch kind { + case StepClick, StepFill, StepAssert, StepSubmit: + default: + return step, hcl.Diagnostics{{ + Severity: hcl.DiagError, + Summary: "Unrecognized step kind", + Detail: fmt.Sprintf("step %q: must be one of click, fill, assert, submit.", kind), + Subject: &b.LabelRanges[0], + }} + } + + content, diags := b.Body.Content(stepSchema(kind)) + if diags.HasErrors() { + return step, diags + } + + str := func(name string) (string, bool) { + attr, ok := content.Attributes[name] + if !ok { + return "", false + } + v, vdiags := evalString(attr.Expr, ctx) + diags = diags.Extend(vdiags) + if vdiags.HasErrors() { + return "", false + } + return v, true + } + + step.Selector, _ = str("selector") + switch kind { + case StepFill: + step.Value, _ = str("value") + case StepAssert: + step.Text, step.HasText = str("text") + } + return step, diags +} diff --git a/hclscenario/schema_test.go b/hclscenario/schema_test.go new file mode 100644 index 0000000..591c0e7 --- /dev/null +++ b/hclscenario/schema_test.go @@ -0,0 +1,183 @@ +// Copyright (c) the go-webengine/webtest authors. +// SPDX-License-Identifier: BSD-3-Clause + +package hclscenario + +import "testing" + +const validScenario = ` +scenario "login" { + url = "https://example.com/login" + + pin { + selectors = ["#login-form", "#username"] + } + + step "fill" { + selector = "#username" + value = upper("alice") + } + step "fill" { + selector = "#password" + value = "s3cr3t" + } + step "click" { + selector = "#submit" + } + step "assert" { + selector = "#welcome" + text = "Welcome, ALICE" + } + step "submit" { + selector = "#login-form" + } +} +` + +func TestParseValidScenario(t *testing.T) { + sc, diags := Parse([]byte(validScenario), "test.hcl") + if diags.HasErrors() { + t.Fatalf("Parse: %v", diags) + } + if sc.Name != "login" { + t.Fatalf("Name = %q, want login", sc.Name) + } + if sc.URL != "https://example.com/login" { + t.Fatalf("URL = %q", sc.URL) + } + if sc.Pin == nil || len(sc.Pin.Selectors) != 2 { + t.Fatalf("Pin = %+v, want 2 selectors", sc.Pin) + } + if len(sc.Steps) != 5 { + t.Fatalf("len(Steps) = %d, want 5", len(sc.Steps)) + } + if sc.Steps[0].Kind != StepFill || sc.Steps[0].Value != "ALICE" { + t.Fatalf("Steps[0] = %+v, want fill value=ALICE (via upper())", sc.Steps[0]) + } + if sc.Steps[3].Kind != StepAssert || !sc.Steps[3].HasText || sc.Steps[3].Text != "Welcome, ALICE" { + t.Fatalf("Steps[3] = %+v", sc.Steps[3]) + } + if sc.Steps[4].Kind != StepSubmit || sc.Steps[4].Selector != "#login-form" { + t.Fatalf("Steps[4] = %+v", sc.Steps[4]) + } +} + +func TestParseAssertWithoutText(t *testing.T) { + src := ` +scenario "s" { + url = "https://x/" + step "assert" { + selector = "#ok" + } +} +` + sc, diags := Parse([]byte(src), "test.hcl") + if diags.HasErrors() { + t.Fatalf("Parse: %v", diags) + } + if sc.Steps[0].HasText { + t.Fatalf("HasText = true for an assert step with no text attribute, want false") + } +} + +func TestParseNoScenarioBlock(t *testing.T) { + _, diags := Parse([]byte(`not_a_scenario "x" {}`), "test.hcl") + if !diags.HasErrors() { + t.Fatal("Parse with no scenario block: want an error") + } +} + +func TestParseTwoScenarioBlocks(t *testing.T) { + src := ` +scenario "a" { + url = "https://x/" +} +scenario "b" { + url = "https://y/" +} +` + _, diags := Parse([]byte(src), "test.hcl") + if !diags.HasErrors() { + t.Fatal("Parse with two scenario blocks: want an error (exactly one is required)") + } +} + +func TestParseMissingRequiredURL(t *testing.T) { + _, diags := Parse([]byte(`scenario "s" { }`), "test.hcl") + if !diags.HasErrors() { + t.Fatal("Parse with no url attribute: want an error") + } +} + +func TestParseUnrecognizedStepKind(t *testing.T) { + src := ` +scenario "s" { + url = "https://x/" + step "teleport" { + selector = "#a" + } +} +` + _, diags := Parse([]byte(src), "test.hcl") + if !diags.HasErrors() { + t.Fatal(`Parse with step "teleport": want an error`) + } +} + +func TestParseUnregisteredFunctionCall(t *testing.T) { + src := ` +scenario "s" { + url = "https://x/" + step "fill" { + selector = "#a" + value = reverse("x") + } +} +` + _, diags := Parse([]byte(src), "test.hcl") + if !diags.HasErrors() { + t.Fatal(`Parse calling an unregistered function "reverse": want an error, not a silent null`) + } +} + +func TestParseFillMissingValue(t *testing.T) { + src := ` +scenario "s" { + url = "https://x/" + step "fill" { + selector = "#a" + } +} +` + _, diags := Parse([]byte(src), "test.hcl") + if !diags.HasErrors() { + t.Fatal(`Parse fill step with no value: want an error`) + } +} + +func TestParsePinNoSelectors(t *testing.T) { + src := ` +scenario "s" { + url = "https://x/" + pin {} +} +` + _, diags := Parse([]byte(src), "test.hcl") + if !diags.HasErrors() { + t.Fatal("Parse pin block with no selectors attribute: want an error") + } +} + +func TestParseEmptySource(t *testing.T) { + _, diags := Parse([]byte(``), "test.hcl") + if !diags.HasErrors() { + t.Fatal("Parse of an empty file: want an error (no scenario block)") + } +} + +func TestParseSyntaxError(t *testing.T) { + _, diags := Parse([]byte(`scenario "s" { url = `), "test.hcl") + if !diags.HasErrors() { + t.Fatal("Parse of truncated/invalid syntax: want an error") + } +} diff --git a/hclscenario/testdata/fuzz/FuzzParseScenario/4941ee77dd913a51 b/hclscenario/testdata/fuzz/FuzzParseScenario/4941ee77dd913a51 new file mode 100644 index 0000000..c713453 --- /dev/null +++ b/hclscenario/testdata/fuzz/FuzzParseScenario/4941ee77dd913a51 @@ -0,0 +1,2 @@ +go test fuzz v1 +string("scenario \"0\" {\nurl ={}\n} ")