From 68a96975005bcda07fd8615bbf495099988f37be Mon Sep 17 00:00:00 2001
From: Chad Ostrowski <221614+chadoh@users.noreply.github.com>
Date: Sat, 24 Oct 2026 07:55:53 -0400
Subject: [PATCH] docs: better comments in `e2e`

Previous comments were useful to Scaffold's secondary audience: the
maintainers of Scaffold.

This targets them at Scaffold's primary audience: consumers who
generated an app with it.

`e2e` is useful to both, but these comments made it seem like they were
included in generated apps by accident. (See stellar-scaffold/cli#638)
---
 e2e/package.json                   |  2 +-
 e2e/playwright.config.ts           | 16 ++++++++++------
 e2e/tests/guess-the-number.spec.ts |  9 ---------
 e2e/tests/smoke.spec.ts            |  5 -----
 e2e/tests/visual.spec.ts           |  9 ++++++---
 5 files changed, 17 insertions(+), 24 deletions(-)

diff --git a/e2e/package.json b/e2e/package.json
index e668a6a5..2772c00e 100644
--- a/e2e/package.json
+++ b/e2e/package.json
@@ -3,7 +3,7 @@
   "version": "0.0.0",
   "private": true,
   "type": "module",
-  "description": "Playwright UI-smoke parity tests run against every framework template.",
+  "description": "Playwright e2e UI tests",
   "scripts": {
     "test": "playwright test"
   },
diff --git a/e2e/playwright.config.ts b/e2e/playwright.config.ts
index 36a067c9..c9876a39 100644
--- a/e2e/playwright.config.ts
+++ b/e2e/playwright.config.ts
@@ -3,21 +3,25 @@ import { existsSync, readdirSync } from "node:fs"
 import { dirname, resolve } from "node:path"
 import { fileURLToPath } from "node:url"
 
-// Self-adapting target list, so the same suite works in both lifecycle states
-// without `init` having to rewrite this file:
-//   - Post-init (user project): only the instantiated `app/` exists → 1 target.
-//   - Contributor view (UI monorepo): one target per `templates/<framework>/`.
-// The shared, framework-agnostic specs then run against whichever targets exist,
-// which is what enforces feature parity between templates.
 const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..")
 
 type Target = { name: string; cwd: string; port: number }
 
+// These tests run in both a generated Scaffold project (which has an `app`
+// dir) and in the Scaffold UI monorepo (which has a `templates` dir). They are
+// how the Scaffold team maintains parity and behavior for all of their
+// templates, and they are also useful as a starting point for app developers
+// who use Scaffold to initialize projects.
+//
+// If you used Scaffold to generate this project, feel free to simplify this
+// function to remove the `templates` logic.
 function resolveTargets(): Target[] {
+	// generated Scaffold project
 	const appDir = resolve(repoRoot, "app")
 	if (existsSync(appDir)) {
 		return [{ name: "app", cwd: appDir, port: 5180 }]
 	}
+	// the Scaffold UI monorepo (feel free to remove)
 	const templatesDir = resolve(repoRoot, "templates")
 	const frameworks = existsSync(templatesDir)
 		? readdirSync(templatesDir, { withFileTypes: true })
diff --git a/e2e/tests/guess-the-number.spec.ts b/e2e/tests/guess-the-number.spec.ts
index a43f0927..920d3dbe 100644
--- a/e2e/tests/guess-the-number.spec.ts
+++ b/e2e/tests/guess-the-number.spec.ts
@@ -3,15 +3,6 @@ import { Keypair, xdr } from "@stellar/stellar-sdk"
 import { connectFakeFreighter, DECLINED } from "../util/fake-freighter"
 import { CONTRACT_ERROR, stubRpc } from "../util/stub-rpc"
 
-// Guess the Number, from typing a guess to the result the player sees. The
-// wallet and the RPC are stand-ins (see `../util`), so these run the same
-// against every target and network with no chain, extension or funded account.
-//
-// Regression guard for stellar-scaffold/ui#285: a guess must reach the
-// contract call and the wallet, the contract's answer must reach the player,
-// and a failure along the way (declined signature, simulation or contract
-// error) must not read as a wrong guess.
-
 const guesser = Keypair.random()
 const INCORRECT = "Incorrect guess. Try again!"
 const CORRECT = "You got it!"
diff --git a/e2e/tests/smoke.spec.ts b/e2e/tests/smoke.spec.ts
index 0772acb7..0bb35275 100644
--- a/e2e/tests/smoke.spec.ts
+++ b/e2e/tests/smoke.spec.ts
@@ -1,10 +1,5 @@
 import { test, expect } from "@playwright/test"
 
-// UI-smoke parity: framework-agnostic assertions that must hold for every
-// target (each framework template in the monorepo, or the single `app/` after
-// init). These guard the shared-util/component/style refactor against dropped
-// features and broken imports — no chain or wallet interaction required.
-
 test("home page mounts", async ({ page }) => {
 	const response = await page.goto("/")
 	expect(response?.ok()).toBeTruthy()
diff --git a/e2e/tests/visual.spec.ts b/e2e/tests/visual.spec.ts
index 9e6c1315..da03bc98 100644
--- a/e2e/tests/visual.spec.ts
+++ b/e2e/tests/visual.spec.ts
@@ -1,9 +1,12 @@
 import { test, expect } from "@playwright/test"
 
-// Visual guard for the styles centralization. Per-project baselines (one per
-// framework) are committed; the smoke specs assert behavior, these assert
-// appearance. During the styles refactor an intended change shows up as a diff
+// Visual guard for the styles centralization. Saves png snapshots of current
+// UI and compares against previous run's png.
+//
+// During a style refactor an intended change shows up as a diff
 // to review + re-baseline (`--update-snapshots`); an unintended one fails.
+//
+// First run fails, generating an initial png.
 
 test("home page visual", async ({ page }) => {
 	await page.goto("/")