Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 53 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -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 ./...
56 changes: 55 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
@@ -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.
21 changes: 21 additions & 0 deletions go.mod
Original file line number Diff line number Diff line change
@@ -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
)
28 changes: 28 additions & 0 deletions go.sum
Original file line number Diff line number Diff line change
@@ -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=
78 changes: 78 additions & 0 deletions hclscenario/functions.go
Original file line number Diff line number Diff line change
@@ -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
},
})
71 changes: 71 additions & 0 deletions hclscenario/functions_test.go
Original file line number Diff line number Diff line change
@@ -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)
}
}
}
35 changes: 35 additions & 0 deletions hclscenario/fuzz_test.go
Original file line number Diff line number Diff line change
@@ -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")
})
}
Loading
Loading