@mechris3/glassbox 0.1.4 → 0.1.5

package/README.md

@@ -179,7 +179,78 @@ export default defineConfig({
 });
 ```
 
-### Lifecycle Hooks
+### Best Practices
+
+### Journeys are pure orchestration
+
+A journey's `execute()` method should contain **only** calls to page object methods — no conditionals, no assertions, no direct selectors:
+
+```typescript
+// Good — reads like a user story
+async execute() {
+  await this.loginPage.loginAs('alice@company.com', 'alice123');
+  await this.dashboardPage.verifyLoaded();
+  await this.dashboardPage.navigateToProjects();
+  await this.projectsPage.verifyProjectCount(6);
+}
+
+// Bad — logic leaking into journey
+async execute() {
+  await this.fill('[data-testid="email"]', 'alice@company.com');
+  const count = await this.getText('[data-testid="count"]');
+  if (parseInt(count) !== 6) throw new Error('wrong');
+}
+```
+
+### Page objects own everything
+
+- **Selectors** — store in a private `selectors` object, never expose them
+- **Interaction** — `loginAs()`, `addTask()`, `filterByStatus()` — intention-revealing names
+- **Validation** — `verifyLoaded()`, `verifyErrorMessage()`, `verifyTaskCount()` — throw descriptive errors on failure
+
+```typescript
+export class ProjectsPage extends BasePage {
+  private selectors = {
+    projectCard: '[data-testid="project-card"]',
+    filterActive: '[data-testid="filter-active"]',
+    count: '[data-testid="project-count"]',
+  };
+
+  async filterByActive() {
+    await this.click(this.selectors.filterActive);
+  }
+
+  async verifyProjectCount(expected: number) {
+    const count = await this.getText(this.selectors.count);
+    if (count !== String(expected)) {
+      throw new Error(`Expected ${expected} projects, got ${count}`);
+    }
+  }
+}
+```
+
+### Selector strategy
+
+- Always use `[data-testid="..."]` — never CSS classes, tag names, or DOM structure
+- For repeated items, include an identifier: `[data-testid="task-item-${id}"]`
+- If an element doesn't have a `data-testid`, add one to your app first
+
+### File organisation
+
+```
+glassbox/
+├── page-objects/
+│   ├── login.page.ts        ← one class per file
+│   ├── dashboard.page.ts
+│   └── projects.page.ts
+├── journeys/
+│   ├── login-and-browse.journey.ts
+│   └── create-task.journey.ts
+└── helpers/
+    └── before-each.ts
+```
+
+## Lifecycle Hooks
 
 Run code before/after journeys for test data setup and cleanup:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mechris3/glassbox",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Debugger-style browser automation test runner with live execution control via CDP",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",