@mechris3/glassbox 0.1.3 → 0.1.5

package/README.md

@@ -76,6 +76,28 @@ Either way, run `glassbox` commands from the directory containing your `glassbox
 - Node.js 20+
 - A Chromium-based browser (Chrome, Brave, Edge)
 
+## Environment Variables
+
+Config files, hooks, journeys, and page objects are all TypeScript running in Node — `process.env` works everywhere:
+
+```typescript
+// page-objects/login.page.ts — credentials from env
+async login() {
+  const user = process.env.TEST_USERNAME ?? 'default@test.com';
+  const pass = process.env.TEST_PASSWORD ?? 'password123';
+  await this.fill('[data-testid="email"]', user);
+  await this.fill('[data-testid="password"]', pass);
+  await this.click('[data-testid="submit"]');
+}
+
+// glassbox.config.ts — headless in CI
+browser: { headless: process.env.CI === 'true' }
+
+// helpers/before-each.ts — API key for test data service
+const apiKey = process.env.TEST_API_KEY;
+await fetch('http://...', { headers: { Authorization: `Bearer ${apiKey}` } });
+```
+
 ## Consumer Usage
 
 ### Page Objects
@@ -157,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.3",
+  "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",