test-casebook 1.0.0

package/bin/test-casebook.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+import { cpSync, existsSync, mkdirSync, readdirSync, statSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const pkgRoot = dirname(here);
+const cwd = process.cwd();
+const args = process.argv.slice(2);
+const command = args[0];
+const force = args.includes("--force");
+
+const ASSETS = ["AGENTS.md", "docs", ".claude"];
+
+function walk(dir) {
+  const out = [];
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) out.push(...walk(full));
+    else out.push(full);
+  }
+  return out;
+}
+
+function copyAsset(name) {
+  const src = join(pkgRoot, name);
+  if (!existsSync(src)) return { copied: [], skipped: [] };
+  const copied = [];
+  const skipped = [];
+  const files = statSync(src).isDirectory() ? walk(src) : [src];
+  for (const file of files) {
+    const rel = relative(pkgRoot, file);
+    const dest = join(cwd, rel);
+    if (existsSync(dest) && !force) {
+      skipped.push(rel);
+      continue;
+    }
+    mkdirSync(dirname(dest), { recursive: true });
+    cpSync(file, dest);
+    copied.push(rel);
+  }
+  return { copied, skipped };
+}
+
+function init() {
+  const copied = [];
+  const skipped = [];
+  for (const asset of ASSETS) {
+    const result = copyAsset(asset);
+    copied.push(...result.copied);
+    skipped.push(...result.skipped);
+  }
+  console.log(`\ntest-casebook — scaffolded into ${cwd}\n`);
+  if (copied.length) {
+    console.log(`Added ${copied.length} file(s):`);
+    for (const file of copied) console.log(`  + ${file}`);
+  }
+  if (skipped.length) {
+    console.log(
+      `\nSkipped ${skipped.length} existing file(s) (use --force to overwrite):`,
+    );
+    for (const file of skipped) console.log(`  = ${file}`);
+  }
+  console.log(`\nNext steps:`);
+  console.log(
+    `  1. Open this project in Claude Code and invoke the "test-casebook" skill.`,
+  );
+  console.log(
+    `  2. env-attr-cleaner (the cleaner) is OPTIONAL and never auto-installed.`,
+  );
+  console.log(
+    `     To strip data-test-* from production builds, install it yourself:`,
+  );
+  console.log(
+    `       npm i -D env-attr-cleaner   (or pnpm add -D / yarn add -D)`,
+  );
+  console.log(
+    `     then wire it per the env-attr-cleaner repo's docs/frameworks.\n`,
+  );
+}
+
+function usage() {
+  console.log(`test-casebook — testing methodology scaffolder\n`);
+  console.log(`Usage:`);
+  console.log(`  npx test-casebook init [--force]\n`);
+  console.log(
+    `  init     copy AGENTS.md, docs/ and .claude/ into the current project`,
+  );
+  console.log(`  --force  overwrite files that already exist\n`);
+}
+
+if (command === "init") init();
+else usage();

package/docs/conventions.md

@@ -0,0 +1,127 @@
+
+# Conventions - Data Attributes
+
+## Test Attributes
+
+### `data-test-id`
+
+Unique identifier for a specific element.
+
+```html
+<button data-test-id="login-submit">Connexion</button>
+<input data-test-id="login-email" type="email">
+<form data-test-id="login-form">
+```
+
+**Naming**: `context-element` or `context-action`
+
+```
+login-submit
+login-email
+cart-checkout-button
+product-123-add-to-cart
+```
+
+### `data-test-class`
+
+Group similar elements for counting or filtering.
+
+```html
+<div data-test-class="product-card">...</div>
+<div data-test-class="product-card">...</div>
+<div data-test-class="product-card featured">...</div>
+```
+
+**Usage in tests**:
+
+```ts
+// Compter
+const cards = page.locator('[data-test-class~="product-card"]')
+await expect(cards).toHaveCount(3)
+
+// Filtrer
+const featured = page.locator('[data-test-class~="featured"]')
+```
+
+## Debug Attributes (Phase 2)
+
+### `data-state`
+
+Current business state of a component.
+
+```html
+<form data-state="idle">
+<form data-state="loading">
+<form data-state="success">
+<form data-state="error">
+```
+
+### `data-error`
+
+Error context for debugging.
+
+```html
+<div data-error="validation-failed">
+<div data-error="network-timeout">
+```
+
+### `data-last-action`
+
+Last user action for debugging.
+
+```html
+<div data-last-action="submit-clicked">
+<div data-last-action="field-focused">
+```
+
+## Feature Flags (Phase 3)
+
+### `data-present`
+
+Track if an element should be present.
+
+```html
+<div data-present="premium-feature">
+```
+
+### `data-experiment` / `data-variant`
+
+A/B test tracking.
+
+```html
+<button data-experiment="checkout-flow" data-variant="one-click">
+```
+
+## Analytics (Phase 4)
+
+### `data-analytics-*`
+
+Analytics event tracking.
+
+```html
+<button
+    data-analytics-event="click"
+    data-analytics-category="checkout"
+    data-analytics-label="buy-now"
+>
+```
+
+## Configuration by Environment
+
+```ts
+envAttrCleaner({
+    environments: {
+        // Tous les attributs en developpement
+        development: ['data-test-*', 'data-debug-*', 'data-analytics-*'],
+
+        // Uniquement les attributs de test en CI
+        test: ['data-test-*'],
+
+        // Test + analytics en staging
+        staging: ['data-test-*', 'data-analytics-*'],
+
+        // Uniquement analytics en production (ou rien)
+        production: ['data-analytics-*']
+    }
+})
+```

package/docs/strategy.md

@@ -0,0 +1,100 @@
+
+# Strategy - Why Data Attributes for Testing
+
+## The Problem
+
+Traditional selectors are **fragile**:
+
+```ts
+// Breaks when CSS changes
+cy.get('.btn-primary')
+
+// Breaks when structure changes
+cy.get('form > div:nth-child(2) > button')
+
+// Breaks when text changes
+cy.get('button').contains('Envoyer')
+```
+
+## The Solution
+
+Data attributes are **stable**:
+
+```ts
+// Never breaks unless intentionally changed
+cy.get('[data-test-id="submit-button"]')
+```
+
+## Why It Works
+
+| Selector type | Stability | Readability |
+|---------------|-----------|-------------|
+| CSS classes | Low | Medium |
+| DOM structure | Very low | Low |
+| Text content | Low | High |
+| `data-test-*` | **High** | **High** |
+
+## Conventions
+
+### `data-test-id` - Target a unique element
+
+```html
+<button data-test-id="login-submit">Connexion</button>
+```
+
+```ts
+page.locator('[data-test-id="login-submit"]')
+```
+
+### `data-test-class` - Group elements
+
+```html
+<div data-test-class="product-card">Produit 1</div>
+<div data-test-class="product-card">Produit 2</div>
+<div data-test-class="product-card">Produit 3</div>
+```
+
+```ts
+const cards = page.locator('[data-test-class="product-card"]')
+await expect(cards).toHaveCount(3)
+```
+
+## Adoption Roadmap
+
+### Phase 1 - Testing (immediate value)
+
+```
+data-test-id      -> unique element targeting
+data-test-class   -> group counting and filtering
+```
+
+### Phase 2 - Debug (developer productivity)
+
+```
+data-state        -> visible business state
+data-error        -> error context
+data-last-action  -> last user action
+```
+
+### Phase 3 - Feature Flags / A/B Testing
+
+```
+data-present      -> element presence tracking
+data-experiment   -> A/B test name
+data-variant      -> active variant
+```
+
+### Phase 4 - Analytics
+
+```
+data-analytics-event     -> event name
+data-analytics-category  -> category
+data-analytics-label     -> custom label
+```
+
+## Key Message
+
+> Start by testing better.
+> End up understanding and controlling your application.
+
+Data attributes become a **common language** for the entire frontend: testing, debug, observability, analytics.