@stardeck-customer-apps/testing 0.5.0 → 0.5.1

package/SKILL.md

@@ -53,7 +53,7 @@ beforeEach(() => app.reset());
 afterAll(() => app.close());
 
 describeWorkflow("checkout", () => {
-  it("completes an order, decrements stock, and emails the customer", async () => {
+  it("someone buys a widget and gets a confirmation email", async () => {
     const user = app.asUser({ email: "buyer@example.com" });
 
     const res = await callRoute(checkout, { body: { items: [{ sku: "Widget", qty: 2 }] } });
@@ -153,6 +153,23 @@ expect(app.edge.latestDisplay()?.action).toBe("show");
   ("checkout", "booking", "inventory"). The platform reports these per
   deployment — every critical workflow should have one.
 
+### Naming
+
+The app owner reads these names in the dashboard, under the workflow, without
+ever opening the code. Name the workflow after the business capability, and name
+each test after the thing a person does, in a full sentence:
+
+```ts
+describeWorkflow("checkout", () => {
+  it("someone adds an item to their cart", ...);
+  it("someone pays for their cart with a credit card", ...);
+  it("someone whose card is declined keeps their cart", ...);
+});
+```
+
+Not `it("POST /api/checkout returns 200")` or `it("decrements stock")` — those
+describe the code, and the owner can't tell from them what is or isn't covered.
+
 ## What works out of the box
 
 - `DataStoreClient` (query/insert/update/delete/schema ops) — served by the

package/dist/index.d.mts

@@ -353,6 +353,10 @@ declare function createTestApp(options?: TestAppOptions): Promise<TestApp>;
  * "booking", "inventory"). The platform parses the `workflow:` prefix out of
  * test reporter output to show per-workflow pass/fail on deployments — use
  * one block per workflow the app's owner cares about.
+ *
+ * The dashboard lists the workflow's test names beneath it, so title each test
+ * as a sentence about what a person does ("someone pays with a credit card"),
+ * not about the code under it.
  */
 declare function describeWorkflow(name: string, fn: () => void): void;
 declare const WORKFLOW_NAME_PREFIX = "workflow:";

package/dist/index.d.ts

@@ -353,6 +353,10 @@ declare function createTestApp(options?: TestAppOptions): Promise<TestApp>;
  * "booking", "inventory"). The platform parses the `workflow:` prefix out of
  * test reporter output to show per-workflow pass/fail on deployments — use
  * one block per workflow the app's owner cares about.
+ *
+ * The dashboard lists the workflow's test names beneath it, so title each test
+ * as a sentence about what a person does ("someone pays with a credit card"),
+ * not about the code under it.
  */
 declare function describeWorkflow(name: string, fn: () => void): void;
 declare const WORKFLOW_NAME_PREFIX = "workflow:";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stardeck-customer-apps/testing",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Vitest test harness for Stardeck customer apps — in-process Postgres (PGlite) plus a control-plane simulator so the real Stardeck SDKs run unmodified in tests",
   "main": "dist/index.js",
   "module": "dist/index.mjs",