e2e

package
v0.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 15, 2026 License: MIT Imports: 20 Imported by: 0

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

Constants

This section is empty.

Variables

View Source
var AppOrder = []string{"native"}

AppOrder lists the example apps (mirrors examples/server/render.go): the native app is the only one.

View Source
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

func Register

func Register(list ...Scenario)

Register adds scenarios to the suite, after the ones registered before. Call it from an init function of a file of this package.

func Run

func Run(ctx context.Context, o Options) int

Run starts the example server, runs the scenarios and prints the matrix. It returns 0, or 1 when --strict is set and a scenario failed or nothing ran.

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

type Env struct {
	Page *Page
	Base string
	App  string
}

Env is what a scenario gets: the page, the app and a few helpers.

func (*Env) API

func (e *Env) API(path string) string

API is the address of an endpoint of the app's API.

func (*Env) Assert

func (e *Env) Assert(cond bool, message string)

Assert fails the scenario when cond is false.

func (*Env) Equal

func (e *Env) Equal(actual, expected any, message string)

Equal compares two values by their JSON form.

func (*Env) Get

func (e *Env) Get(url string) string

Get returns the body of a GET request made outside the page.

func (*Env) Open

func (e *Env) Open()

Open loads the app's page and waits until it is ready.

func (*Env) Reset

func (e *Env) Reset()

Reset restores the server's state for the app.

func (*Env) Stats

func (e *Env) Stats() Stats

Stats reads the server's counters for the app.

func (*Env) Until

func (e *Env) Until(message string, f func() bool)

Until polls until f is true or five seconds pass.

func (*Env) UntilFor

func (e *Env) UntilFor(message string, timeout time.Duration, f func() bool)

UntilFor polls until f is true or the timeout passes. A step of f that fails is retried; its last failure goes into the message.

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 Outcome

type Outcome struct {
	App     string
	Browser string
	Version string
	Results []Result
}

Outcome is every result of one app in one browser.

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) Click

func (p *Page) Click(sel string)

Click scrolls the element into view and clicks its center with the mouse.

func (*Page) Count

func (p *Page) Count(sel string) int

Count is the number of elements that match the selector.

func (*Page) Eval

func (p *Page) Eval(expr string, out any)

Eval evaluates a JavaScript expression (a promise is awaited) and decodes its JSON value into out, when out is not nil.

func (*Page) Fill

func (p *Page) Fill(sel, value string)

Fill focuses the field, replaces its value and fires the input event, the same steps a user takes to fill a field.

func (*Page) Focus

func (p *Page) Focus(sel string)

Focus gives the element the focus.

func (*Page) Forward

func (p *Page) Forward()

Forward goes one entry forward in the history.

func (*Page) Goto

func (p *Page) Goto(url string)

Goto loads a URL and waits for the load event.

func (*Page) InputValue

func (p *Page) InputValue(sel string) string

InputValue waits for the element and returns its value.

func (*Page) OnDialog

func (p *Page) OnDialog(f func(message string) bool)

OnDialog sets the handler of alert, confirm and prompt dialogs.

func (*Page) PressEnter

func (p *Page) PressEnter(sel string)

PressEnter focuses the element and presses Enter.

func (*Page) PressSequentially

func (p *Page) PressSequentially(sel, text string, delay time.Duration)

PressSequentially types text key by key into the field, pausing between keys.

func (*Page) Sleep

func (p *Page) Sleep(d time.Duration)

Sleep pauses the scenario.

func (*Page) TextContent

func (p *Page) TextContent(sel string) string

TextContent waits for the element and returns its text.

func (*Page) Texts

func (p *Page) Texts(sel string) []string

Texts is the text content of every element that matches the selector.

func (*Page) URL

func (p *Page) URL() string

URL is the current address.

func (*Page) WaitFunction

func (p *Page) WaitFunction(expr string)

WaitFunction waits until the JavaScript expression is truthy.

func (*Page) WaitSelector

func (p *Page) WaitSelector(sel string)

WaitSelector waits until an element matches the selector.

func (*Page) WaitURL

func (p *Page) WaitURL(re *regexp.Regexp, timeout time.Duration)

WaitURL waits until the address matches the regular expression.

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL