Testing and Tooling

Use vtest, snapshots, async assertions, and the Vango CLI workflow to keep apps verifiable and generated artifacts current.

#testing#vtest#cli#diagnostics

Testing and Tooling

Vango ships a practical testing and tooling story that matches its server-driven runtime model.

pkg/vtest

Use pkg/vtest to mount components, interact with them, and inspect resulting HTML or state.

Helpful operations include:

  • HTML(...)

  • AssertSnapshot(...)

  • ExistsByTestID(...)

  • ClickByTestID(...)

  • InputByTestID(...)

  • SubmitByTestID(...)

  • AwaitResource(...)

  • AwaitAction(...)

  • AssertActionState(...)

Prefer data-testid queries over brittle CSS selectors.

Snapshot testing

Use snapshots for:

  • structural output

  • major visual state transitions

  • route-level page output

Use targeted assertions for counts, error text, action state, and critical fields.

Async testing

Do not sleep in tests.

Use the await helpers for Resource and Action state, and inject deterministic fake services into async boundaries.

Keep external I/O out of unit tests.

CLI workflow

Core commands:

  • vango create

  • vango dev

  • vango build

  • vango test

  • vango gen routes

  • vango gen bindings

  • vango state plan

  • vango state apply

  • vango state impact

  • vango inspect state --json

  • vango lint

Normal loop:

  1. edit code

  2. run vango dev

  3. commit code plus generated artifacts

vango dev reload transport

Treat the dev reload socket as an auxiliary DX channel, not the main runtime transport.

If hot reload disconnects repeatedly, inspect runtime endpoint prefixing, proxy handling, and idle WebSocket timeouts before assuming the framework is at fault.

Diagnostics

Diagnostics are meant to be machine-readable and stable. Read them literally.

Common failures map directly to contract violations:

  • conditional allocation

  • render allocation

  • stale bindings or manifest

  • schema mismatch after deploy

  • patch mismatch or self-heal reloads

  • persist budget failures

Completion checklist

Before you finish a change, confirm:

  • no setup.* allocation in render

  • no blocking work on the session loop

  • no manual goroutines in Setup, render, handlers, or lifecycle callbacks

  • no page-handler or render-time ctx.Navigate(...)

  • all dynamic lists have stable keys

  • no ad hoc DOM mutation outside explicit client boundaries

  • route-owned forms use page Action plus setup.RouteForm

  • generated routes and state artifacts are current

For a compact inventory of the main app-building surface, see API Reference.