@mechris3/glassbox 0.1.4 → 0.1.6

package/README.md

@@ -102,7 +102,26 @@ await fetch('http://...', { headers: { Authorization: `Bearer ${apiKey}` } });
 
 ### Page Objects
 
-Extend `BasePage` — no constructor needed:
+Extend `BasePage` — no constructor needed. The following methods are available via `this`:
+
+| Method | Description |
+|--------|-------------|
+| `click(selector)` | Click an element |
+| `fill(selector, value)` | Clear and set an input's value |
+| `type(selector, value, {delay?})` | Type character by character (for autocomplete etc.) |
+| `getText(selector)` | Get an element's text content |
+| `getInputValue(selector)` | Get an input's current value |
+| `getAttribute(selector, attr)` | Get an element's attribute value |
+| `countElements(selector)` | Count matching elements |
+| `isVisible(selector)` | Check if element is visible |
+| `isDisabled(selector)` | Check if element is disabled |
+| `waitForSelector(selector, {timeout?})` | Wait for element to appear (default 5s) |
+| `waitForHidden(selector, {timeout?})` | Wait for element to disappear |
+| `goto(url)` | Navigate (relative URLs resolve against target URL) |
+| `evaluate(script)` | Execute arbitrary JS in the page |
+| `clearSession(origin?)` | Clear cookies and storage |
+
+Example:
 
 ```typescript
 // page-objects/login.page.ts
@@ -179,7 +198,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.6",
   "description": "Debugger-style browser automation test runner with live execution control via CDP",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",