<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/development/testing/ui-e2e/">
  <id>https://docs.spec-kitty.ai/development/testing/ui-e2e/</id>
  <title>UI End-to-End Tests (Playwright)</title>
  <updated>2026-10-01T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/development/testing/ui-e2e/"/>
  <summary>Lessons for browser-driven UI regression tests; the in-repo dashboard Playwright suite was removed with the dashboard (#5530).</summary>
  <content type="html">&lt;span id=&quot;ui-end-to-end-tests-playwright&quot;&gt;&lt;/span&gt;
&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Status (2026-10-01):&lt;/strong&gt; the bundled local web dashboard was removed from the
CLI (&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/5530&quot;&gt;#5530&lt;/a&gt;), together
with the &lt;code dir=&quot;auto&quot;&gt;tests/ui/&lt;/code&gt; Playwright suite, its fixtures and the &lt;code dir=&quot;auto&quot;&gt;pytest-playwright&lt;/code&gt;
test dependency. The CLI has no web UI to test. A replacement UI built on the
planned Mission Status Read API
(&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/5528&quot;&gt;#5528&lt;/a&gt;) will live in its
own repository and carry its own browser-driven suite. Restore the old suite
from git history (mission &lt;code dir=&quot;auto&quot;&gt;playwright-ui-e2e-bootstrap-01KWX72W&lt;/code&gt;, issue
&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/1008&quot;&gt;#1008&lt;/a&gt;) if it is useful there.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;h2 id=&quot;why-browser-driven-tests&quot;&gt;Why browser-driven tests&lt;/h2&gt;
&lt;p&gt;Backend and API tests cannot catch a bug where the server responds correctly
but the browser renders it wrong. That is exactly what shipped in PR #970: 338
backend tests and every architectural test passed while the dashboard’s WP-card
click-through modal silently dropped the agent identity, because no test layer
exercised the click-then-render flow. &lt;code dir=&quot;auto&quot;&gt;CLAUDE.md&lt;/code&gt;’s “Never claim the frontend
works without Playwright proof” rule comes from that incident.&lt;/p&gt;
&lt;h2 id=&quot;lessons-to-carry-into-any-future-ui-suite&quot;&gt;Lessons to carry into any future UI suite&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Boot the app hermetically.&lt;/strong&gt; Run it in-thread on an ephemeral port against
a synthetic project root; never reuse a singleton that detaches a process or
kills siblings on a shared port range.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Seed fixture data in the exact shape the reader consumes&lt;/strong&gt;, and keep that
synthetic shape in one shared fixture so every test agrees with it.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Wait for real state, never a fixed sleep.&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Assert the pre-interaction baseline first&lt;/strong&gt;, so a later “populated”
assertion proves a real transition.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Scope every assertion to the container under test&lt;/strong&gt;, never page-global:
a field that also renders elsewhere on the page makes a page-global check
pass even when the feature under test is broken.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Prove non-vacuity before committing&lt;/strong&gt;: break the render path (not the
fixture data) and confirm the test fails, then revert.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Run headless&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;PWHEADLESS=1&lt;/code&gt;) and record the command and result in the PR.&lt;/li&gt;
&lt;/ol&gt;</content>
</entry>
