Documentation
¶
Overview ¶
Package e2e runs the end to end scenarios of the example app (examples/native), driven in Chrome, Firefox and Safari against the Go example server (examples/server). It is what "ypy test --suite e2e" runs. Chrome is driven through the DevTools protocol, Firefox and Safari through WebDriver; see Driver.
Index ¶
- Variables
- func Register(list ...Scenario)
- func Run(ctx context.Context, o Options) int
- type Driver
- type Env
- func (e *Env) API(path string) string
- func (e *Env) Assert(cond bool, message string)
- func (e *Env) Equal(actual, expected any, message string)
- func (e *Env) Get(url string) string
- func (e *Env) Open()
- func (e *Env) Reset()
- func (e *Env) Stats() Stats
- func (e *Env) Until(message string, f func() bool)
- func (e *Env) UntilFor(message string, timeout time.Duration, f func() bool)
- type Options
- type Outcome
- type Page
- func (p *Page) Back()
- func (p *Page) Click(sel string)
- func (p *Page) Count(sel string) int
- func (p *Page) Eval(expr string, out any)
- func (p *Page) Fill(sel, value string)
- func (p *Page) Focus(sel string)
- func (p *Page) Forward()
- func (p *Page) Goto(url string)
- func (p *Page) InputValue(sel string) string
- func (p *Page) OnDialog(f func(message string) bool)
- func (p *Page) PressEnter(sel string)
- func (p *Page) PressSequentially(sel, text string, delay time.Duration)
- func (p *Page) Sleep(d time.Duration)
- func (p *Page) TextContent(sel string) string
- func (p *Page) Texts(sel string) []string
- func (p *Page) URL() string
- func (p *Page) WaitFunction(expr string)
- func (p *Page) WaitSelector(sel string)
- func (p *Page) WaitURL(re *regexp.Regexp, timeout time.Duration)
- type Result
- type Scenario
- type Stats
Constants ¶
This section is empty.
Variables ¶
var AppOrder = []string{"native"}
AppOrder lists the example apps (mirrors examples/server/render.go): the native app is the only one.
var Scenarios = []Scenario{ {Name: "lib/global", Run: func(e *Env) { var v map[string]any e.Page.Eval(`({ t: typeof window.ypy, ajax: typeof window.ypy?.ajax, on: typeof window.ypy?.on })`, &v) e.Equal(v, map[string]any{"t": "object", "ajax": "function", "on": "function"}, "global ypy API") }}, {Name: "crud/list", Run: func(e *Env) { e.Until("three rows loaded", func() bool { return len(e.rowNames()) == 3 }) e.Equal(e.rowNames(), fruits3, "initial rows") }}, {Name: "crud/create", Run: func(e *Env) { p := e.Page e.Until("list loaded", func() bool { return len(e.rowNames()) == 3 }) p.Fill("#create-form input[name=name]", "Durian") p.Click("#create-form button") e.Until("new row appended", func() bool { return contains(e.rowNames(), "Durian") }) e.Equal(e.rowNames(), []string{"Apple", "Banana", "Cherry", "Durian"}, "rows after create") e.Until("form reset after success", func() bool { return p.InputValue("#create-form input[name=name]") == "" }) }}, {Name: "crud/edit-inline", Run: func(e *Env) { p := e.Page e.Until("list loaded", func() bool { return len(e.rowNames()) == 3 }) p.Click(`#items tr[data-id="2"] button.edit`) const input = `#items tr[data-id="2"] input[name=name]` p.WaitSelector(input) e.Equal(p.InputValue(input), "Banana", "edit input is pre-filled") p.Fill(input, "Blueberry") p.Click(`#items tr[data-id="2"] button.save`) e.Until("row shows the saved name", func() bool { return contains(e.rowNames(), "Blueberry") }) e.Equal(p.Count("#items tr.editing"), 0, "row left edit mode") e.Equal(p.Count("#items tr"), 3, "row count unchanged") }}, {Name: "crud/edit-cancel", Run: func(e *Env) { p := e.Page e.Until("list loaded", func() bool { return len(e.rowNames()) == 3 }) p.Click(`#items tr[data-id="1"] button.edit`) p.Fill(`#items tr[data-id="1"] input[name=name]`, "Changed") p.Click(`#items tr[data-id="1"] button.cancel`) e.Until("edit mode closed", func() bool { return p.Count("#items tr.editing") == 0 }) e.Equal(e.rowNames(), fruits3, "rows unchanged by cancel") }}, {Name: "crud/delete-confirm", Run: func(e *Env) { p := e.Page e.Until("list loaded", func() bool { return len(e.rowNames()) == 3 }) message := "" p.OnDialog(func(m string) bool { message = m; return true }) p.Click(`#items tr[data-id="3"] button.delete`) e.Until("row removed", func() bool { return len(e.rowNames()) == 2 }) e.Equal(message, "Delete Cherry?", "confirm message") e.Equal(e.rowNames(), []string{"Apple", "Banana"}, "remaining rows") server := e.Get(e.API("/items")) e.Assert(!strings.Contains(server, "Cherry"), "item deleted on the server") }}, {Name: "crud/delete-dismissed", Run: func(e *Env) { p := e.Page e.Until("list loaded", func() bool { return len(e.rowNames()) == 3 }) p.OnDialog(func(string) bool { return false }) p.Click(`#items tr[data-id="3"] button.delete`) p.Sleep(400 * time.Millisecond) e.Equal(len(e.rowNames()), 3, "nothing deleted when confirm is dismissed") }}, {Name: "errors/5xx-not-swapped", Run: func(e *Env) { p := e.Page e.Until("list loaded", func() bool { return len(e.rowNames()) == 3 }) p.Fill("#create-form input[name=name]", "boom") p.Click("#create-form button") e.Until("error event handled", func() bool { return p.TextContent("#flash") == "Request failed (500)" }) e.Equal(p.Count("#items tr.server-error"), 0, "the 500 body was not swapped in") e.Equal(p.Count("#items tr"), 3, "no row added") }}, {Name: "search/filter", Run: func(e *Env) { p := e.Page e.Until("initial results on load", func() bool { return p.Count("#search-results li.person") == 12 }) p.Fill("#search-input", "ca") e.Until("results filtered", func() bool { return p.Count("#search-results li.person") == 3 }) e.Equal(p.Texts("#search-results li"), []string{"Carla Cruz", "Felipe Fonseca", "Lucas Lima"}, "filtered names") p.Fill("#search-input", "zzz") e.Until("empty state", func() bool { return p.Count("#search-results li.empty") == 1 }) }}, {Name: "search/debounce", Run: func(e *Env) { p := e.Page e.Until("initial results on load", func() bool { return p.Count("#search-results li.person") == 12 }) before := e.Stats().Search p.PressSequentially("#search-input", "maria", 40*time.Millisecond) e.Until("final results", func() bool { return p.Count("#search-results li.empty") == 1 }) p.Sleep(500 * time.Millisecond) after := e.Stats().Search e.Equal(after-before, 1, "one request for a burst of keystrokes (delay:300ms)") }}, {Name: "search/indicator", Run: func(e *Env) { p := e.Page e.Until("initial results on load", func() bool { return p.Count("#search-results li.person") == 12 }) p.Eval(`(() => { window.__sawRequestClass = false const el = document.getElementById('search-indicator') new MutationObserver(() => { if (el.classList.contains('ypy-request')) window.__sawRequestClass = true }) .observe(el, { attributes: true, attributeFilter: ['class'] }) return true })()`, nil) p.Fill("#search-input", "jo") e.Until("results", func() bool { return p.Count("#search-results li.person") == 1 }) var saw, still bool p.Eval("window.__sawRequestClass", &saw) e.Assert(saw, "ypy-request class was set on the indicator during the request") p.Eval("document.getElementById('search-indicator').classList.contains('ypy-request')", &still) e.Assert(!still, "ypy-request class removed afterwards") }}, {Name: "headers/request", Run: func(e *Env) { p := e.Page p.Click("#hdrs-btn") e.Until("headers echoed", func() bool { return strings.Contains(p.TextContent("#hdrs-out"), "ypy-request") }) text := p.TextContent("#hdrs-out") h := map[string]string{} for _, l := range strings.Split(text, "\n") { if i := strings.Index(l, ":"); i >= 0 && i+2 <= len(l) { h[l[:i]] = l[i+2:] } else if i >= 0 { h[l[:i]] = "" } } e.Equal(h["ypy-request"], "true", "YPY-Request") e.Assert(strings.Contains(h["ypy-target"], "hdrs-out"), fmt.Sprintf("YPY-Target names the target (got %s)", h["ypy-target"])) e.Assert(strings.HasPrefix(h["ypy-current-url"], e.Base), fmt.Sprintf("YPY-Current-URL (got %s)", h["ypy-current-url"])) e.Assert(strings.Contains(h["ypy-source"], "hdrs-btn"), fmt.Sprintf("YPY-Source (got %s)", h["ypy-source"])) }}, {Name: "headers/response", Run: func(e *Env) { p := e.Page p.Click("#resp-btn") e.Until("YPY-Retarget and YPY-Reswap honoured", func() bool { return p.Count("#retarget-box p.retargeted") == 1 }) e.Until("YPY-Trigger event dispatched", func() bool { return p.TextContent("#toast") == "toast fired" }) e.Until("YPY-Push-Url pushed the URL", func() bool { return strings.HasSuffix(p.URL(), "/"+e.App+"/pushed") }) e.Equal(p.TextContent("#hdrs-out"), "", "the original target was left alone") }}, {Name: "scroll/infinite", Run: func(e *Env) { p := e.Page e.Until("first page loaded", func() bool { return p.Count("#rows tr.row") >= 10 }) e.Equal(p.Count("#rows tr.row"), 10, "first page has 10 rows") for i := 0; i < 30 && p.Count("#rows tr.row") < 40; i++ { p.Eval("(()=>{window.scrollTo(0, document.documentElement.scrollHeight);return true})()", nil) p.Sleep(200 * time.Millisecond) } e.Equal(p.Count("#rows tr.row"), 40, "all pages loaded by scrolling") var nums []float64 p.Eval("[...document.querySelectorAll('#rows tr.row')].map(r => Number(r.dataset.n))", &nums) e.Equal(nums, nameSeq(40), "rows in order, no duplicates") }}, {Name: "form/invalid-422", Run: func(e *Env) { p := e.Page url := p.URL() p.Click("#signup-form button") e.Until("three validation messages", func() bool { return p.Count("#signup-form .error") == 3 }) e.Equal(p.Texts("#signup-form .error"), []string{ "Name must have at least 2 characters.", "Enter a valid email address.", "Password must have at least 8 characters.", }, "messages") e.Equal(p.URL(), url, "no navigation on validation error") p.Fill("#signup-form input[name=name]", "Ana") p.Fill("#signup-form input[name=email]", "not-an-email") p.Click("#signup-form button") e.Until("two messages left", func() bool { return p.Count("#signup-form .error") == 2 }) e.Equal(p.InputValue("#signup-form input[name=name]"), "Ana", "typed values come back with the form") e.Equal(p.InputValue("#signup-form input[name=email]"), "not-an-email", "typed email comes back") e.Equal(e.Stats().Signups, 0, "nothing created") }}, {Name: "form/valid-redirect", Run: func(e *Env) { p := e.Page p.Fill("#signup-form input[name=name]", "Ana Souza") p.Fill("#signup-form input[name=email]", "ana@example.com") p.Fill("#signup-form input[name=password]", "correct horse") p.Click("#signup-form button") p.WaitURL(thanksURL, 5*time.Second) e.Until("thanks page greets the user", func() bool { return p.TextContent("#who") == "Ana Souza" }) e.Equal(e.Stats().Signups, 1, "one signup recorded") }}, {Name: "sse/stream", Run: func(e *Env) { p := e.Page p.Click("#sse-start") e.UntilFor("three streamed events", 6*time.Second, func() bool { return p.Count("#sse-log li.tick") == 3 }) e.Equal(p.Texts("#sse-log li.tick"), []string{"tick 1", "tick 2", "tick 3"}, "events in order") e.Until("closing event handled", func() bool { return p.TextContent("#sse-status") == "bye" }) p.Sleep(800 * time.Millisecond) s := e.Stats() e.Equal([]int{s.SSEConnections, s.SSEOpen}, []int{1, 0}, "one connection, closed, no reconnect after the close event") e.Equal(p.Count("#sse-log li.tick"), 3, "no duplicate events") }}, {Name: "ws/echo", Run: func(e *Env) { p := e.Page p.Click("#ws-start") e.Until("server greeting swapped in", func() bool { return contains(p.Texts("#ws-log p.msg"), "welcome") }) p.Fill("#ws-form input[name=message]", "hello") p.Click("#ws-form button") e.Until("echo swapped in", func() bool { return contains(p.Texts("#ws-log p.msg"), "echo: hello") }) s := e.Stats() e.Equal([]int{s.WSConnections, s.WSMessages}, []int{1, 1}, "one socket, one message sent") p.Fill("#ws-form input[name=message]", "again") p.PressEnter("#ws-form input[name=message]") e.Until("second echo", func() bool { return contains(p.Texts("#ws-log p.msg"), "echo: again") }) e.Equal(p.Texts("#ws-log p.msg"), []string{"welcome", "echo: hello", "echo: again"}, "log order") }}, {Name: "events/names", Run: func(e *Env) { var seen []struct { N string `json:"n"` Ctx string `json:"ctx"` } e.Page.Eval(`(async () => { const log = [] const n = 'ypy:after:request' document.addEventListener(n, e => log.push({ n, ctx: typeof e.detail?.ctx })) document.getElementById('hdrs-btn').click() const end = Date.now() + 4000 while (!log.length && Date.now() < end) await new Promise(r => setTimeout(r, 50)) return log.slice(0, 1) })()`, &seen) var got [][2]string for _, x := range seen { got = append(got, [2]string{x.N, x.Ctx}) } e.Equal(got, [][2]string{{"ypy:after:request", "object"}}, "event name and detail") }}, }
Scenarios in the order they run.
Functions ¶
Types ¶
type Driver ¶
type Driver interface {
// Goto loads the address and returns after the load event.
Goto(ctx context.Context, url string) error
// Eval runs the async function expression `(async()=>{...})()` built by
// Page.Eval, awaits it and returns the JSON text it produced.
Eval(ctx context.Context, expr string) (string, error)
// Click scrolls the element into view and clicks its center with the
// pointer; it waits for the element to be there.
Click(ctx context.Context, selector string) error
// Type sends the text, key by key, to the element that has the focus.
Type(ctx context.Context, text string) error
// PressEnter presses Enter in the element that has the focus.
PressEnter(ctx context.Context) error
// Back and Forward move through the history of the page.
Back(ctx context.Context) error
Forward(ctx context.Context) error
// Logs are the console lines the page wrote: "error: ...", "warning: ...",
// "uncaught: ...". Chrome reports all of them; WebDriver browsers report
// what happened after the first command that ran in the document.
Logs() []string
// Close ends the page and frees the browser.
Close()
}
Driver is what the scenarios need from a browser, nothing more: open a page, run script in it, click, type, move through the history and read the console. Page builds the scenario helpers (Fill, Count, Texts, WaitSelector ...) on top of it, so a scenario never knows which browser runs it.
There are two implementations: cdpDriver (Chrome, DevTools protocol) and wdDriver (Firefox and Safari, WebDriver). Every method gets the context of the scenario, and an error is a failure of the step.
type Env ¶
Env is what a scenario gets: the page, the app and a few helpers.
type Options ¶
type Options struct {
Root string
Apps string // comma list; empty means every app
Scenario string // only scenarios whose name contains this text
Port int // first port to try (default 8205); the next free one is used
MD string // also write the matrix as markdown to this file
Strict bool // exit 1 when any scenario fails
Browsers []string
ChromePath string
Headed bool
Logs bool
ScenarioTimeout time.Duration
Out, Err io.Writer
Env func(string) string
}
Options of an end to end run.
type Page ¶
type Page struct {
// contains filtered or unexported fields
}
Page is a browser page with the few operations the scenarios use. It is built on a Driver, so the same scenario runs in Chrome, Firefox and Safari.
func (*Page) Back ¶
func (p *Page) Back()
Back goes one entry back in the history and waits for the page to settle.
func (*Page) Eval ¶
Eval evaluates a JavaScript expression (a promise is awaited) and decodes its JSON value into out, when out is not nil.
func (*Page) Fill ¶
Fill focuses the field, replaces its value and fires the input event, the same steps a user takes to fill a field.
func (*Page) InputValue ¶
InputValue waits for the element and returns its value.
func (*Page) PressEnter ¶
PressEnter focuses the element and presses Enter.
func (*Page) PressSequentially ¶
PressSequentially types text key by key into the field, pausing between keys.
func (*Page) TextContent ¶
TextContent waits for the element and returns its text.
func (*Page) WaitFunction ¶
WaitFunction waits until the JavaScript expression is truthy.
func (*Page) WaitSelector ¶
WaitSelector waits until an element matches the selector.
type Result ¶
type Result struct {
Scenario string
Pass bool // false for a scenario that failed; a skipped one is Pass and Skipped
Skipped bool
// SkipReason is why the scenario was left out in this browser (see Scenario.Skip).
SkipReason string
Error string
Duration time.Duration
Console []string
}
Result is the outcome of one scenario.
type Scenario ¶
type Scenario struct {
Name string
Run func(e *Env)
// Skip names the browsers the scenario does not run in, with the reason
// (browser name, as in browsers.Chrome, -> reason). Nil runs everywhere.
Skip map[string]string
}
Scenario is one end to end check of the example app.
type Stats ¶
type Stats struct {
Search int `json:"search"`
SSEConnections int `json:"sseConnections"`
SSEOpen int `json:"sseOpen"`
WSConnections int `json:"wsConnections"`
WSOpen int `json:"wsOpen"`
WSMessages int `json:"wsMessages"`
Signups int `json:"signups"`
}
Stats are the counters of the example server.