@keber/qa-framework 1.1.2 → 1.2.0-0

package/README.md

@@ -28,27 +28,38 @@ This framework was designed to be:
 
 ## Quick Start
 
-### Option A: Install from npm (recommended)
+### Install from npm
 
 ```bash
-npm install --save-dev github:keber/qa-framework
-npx qa-framework init
+npm install @keber/qa-framework
 ```
 
-### Option B: Clone directly (during early adoption)
+The postinstall script scaffolds the `qa/` structure automatically. No need to run `init` manually.
+
+### Using with an AI agent (GitHub Copilot, Claude, etc.)
+
+Use this prompt in your IDE agent chat:
+
+```
+Install @keber/qa-framework, check it's readme file and set up the project for integration with azure devops
+```
+
+The install creates `qa/AGENT-NEXT-STEPS.md` with the exact steps the agent needs to complete the setup (optional integrations, module configuration, credentials, etc.).
+
+### Using manually (without an agent)
 
 ```bash
-# Clone into your project's tools directory or as a submodule
-git clone <this-repo> tools/qa-framework
-node tools/qa-framework/scripts/cli.js init
+npm install @keber/qa-framework
+# then read qa/AGENT-NEXT-STEPS.md for next steps
 ```
 
 The `init` command will:
 
 1. Create the `qa/` directory tree in your project root
-2. Copy all base templates into place
+2. Copy all base templates and agent instructions into place
 3. Create `qa/qa-framework.config.json` for project-specific settings
-4. Optionally set up Playwright and Azure DevOps integrations
+4. Create `.github/copilot-instructions.md` with QA agent behavior rules
+5. Create `qa/AGENT-NEXT-STEPS.md` with follow-up steps
 
 ---
 

package/agent-instructions/04-automation-generation.md

@@ -308,3 +308,33 @@ After writing automation for a module, create `COVERAGE-MAPPING.md` in the test
 | TC-OPER-CAT-003 | Duplicate rejection | ... | tests/operacion/... | ⚠️ Partially (UI only) |
 | TC-OPER-ASI-001 | Access assistance list | ... | — | ⛔ Blocked (BLOCKED-PERMISSIONS) |
 ```
+
+---
+
+## Module Completion Checklist
+
+Run this checklist when all P0 tests for a module are passing.
+
+### Stability gate
+- [ ] All P0 tests pass on **2 consecutive runs** with different `EXEC_IDX` values (≥ 60 seconds apart)
+- [ ] No `waitForTimeout(N)` longer than 2000ms left in the suite
+- [ ] All skipped tests have a `DEF-` or ADO WI reference in their skip message
+
+### Artifacts
+- [ ] `COVERAGE-MAPPING.md` created or updated in the test directory
+- [ ] Execution report written to `qa/05-test-execution/automated/`
+
+### Living Index update — `qa/README.md`
+- [ ] Update the module's row in the status table (TCs automated, date, status → ✅)
+- [ ] Add a row to the `## Sprint History` section with: sprint name, date, submódulos covered, TC count, link to execution report
+
+### AGENT-NEXT-STEPS.md — trim
+- [ ] Move the completed sprint checklist block to `qa/README.md` under `## Sprint History`
+- [ ] Delete the completed sprint section from `AGENT-NEXT-STEPS.md`
+- [ ] Verify `AGENT-NEXT-STEPS.md` now contains **only one active sprint** (the next one)
+
+### Memory
+- [ ] If new patterns or environment quirks were discovered: add them to `qa/memory/` with a descriptive filename
+- [ ] Update `qa/memory/INDEX.md` to reflect any new or updated files
+
+> **Rule**: `AGENT-NEXT-STEPS.md` is a task queue, not a log. Completed sprints live in `qa/README.md`. The file must never accumulate more than one active sprint.

package/agent-instructions/06-maintenance.md

@@ -114,6 +114,13 @@ After every maintenance session, update the master index:
 - Automation status (if changed)
 - Last updated date for the module
 
+If a **sprint was fully completed** as part of this maintenance pass (all TCs passing after the changes):
+1. Move the completed sprint checklist from `AGENT-NEXT-STEPS.md` to the `## Sprint History` section of `qa/README.md`
+2. Delete the completed sprint block from `AGENT-NEXT-STEPS.md`
+3. Confirm `AGENT-NEXT-STEPS.md` contains **only one active sprint** — never let it accumulate history
+
+Also update `qa/memory/INDEX.md` if any memory files were created or modified.
+
 ---
 
 ## Step 6: Write a Session Summary

package/docs/folder-structure-guide.md

@@ -11,6 +11,7 @@ This document explains the purpose, contents, and conventions for every folder i
 ```
 qa/
 ├── README.md                    ← Living master index (project-maintained)
+├── AGENT-NEXT-STEPS.md          ← Active sprint queue for the agent (project-maintained)
 ├── QA-STRUCTURE-GUIDE.md        ← Copy of this guide (installed by framework)
 ├── qa-framework.config.json     ← Project configuration
 │
@@ -23,7 +24,8 @@ qa/
 ├── 05-test-execution/           ← Execution reports and results
 ├── 06-defects/                  ← Defect tracking (optional)
 ├── 07-automation/               ← Automation code (Playwright, etc.)
-└── 08-azure-integration/        ← Azure DevOps integration (optional)
+├── 08-azure-integration/        ← Azure DevOps integration (optional)
+└── memory/                      ← Project QA learnings (project-maintained)
 ```
 
 ---
@@ -267,17 +269,69 @@ See `docs/generalization-decisions.md §7` for the full evaluation of this folde
 
 ## `qa/README.md` — The Living Index
 
-The `qa/README.md` is the **only project-maintained file at the root of `qa/`**. It should be updated whenever:
+The `qa/README.md` is the primary human-readable project status document. It should be updated whenever:
 - A new module is analyzed
 - A new test execution is completed
 - A blocker is identified or resolved
-- A major milestone is reached
+- A major milestone or sprint is completed
 
 Minimum contents:
 - Module status table (name, TCs documented, TCs automated, ADO plan link)
 - Quick-start commands for common tasks
 - Active blockers section
 - Last execution results summary
+- **`## Sprint History`** section — completed sprint checklists moved here from `AGENT-NEXT-STEPS.md`
+
+Template: `templates/qa-readme.md`
+
+---
+
+## `qa/AGENT-NEXT-STEPS.md` — Sprint Queue
+
+The `AGENT-NEXT-STEPS.md` is the agent's task queue for the current sprint. It is read by the agent at the start of every conversation.
+
+**Design principles (SRP + KISS)**:
+- Contains **one active sprint only** — no history, no completed checklists
+- Three sections maximum: module status table, active sprint checklist, context references
+- Does not repeat standing instructions already in `copilot-instructions.md`
+- Detailed environment notes and patterns belong in `qa/memory/`, referenced from here
+
+When a sprint completes, the agent **moves** the completed checklist to `qa/README.md → ## Sprint History` and **deletes** that section from this file.
+
+Template: `templates/agent-next-steps.md`
+
+---
+
+## `qa/memory/` — Project QA Learnings
+
+Project-maintained folder for accumulated knowledge about the application under test: environment quirks, DOM patterns, Playwright gotchas, sprint-specific discoveries.
+
+```
+qa/memory/
+├── INDEX.md                          ← Required entry point — index of all files
+├── {technology}-patterns.md          ← Framework/stack-specific patterns (e.g., playwright-blazor-wasm-patterns.md)
+├── {sprint-name}-discovery.md        ← DOM/UI findings for an in-progress sprint
+└── {sprint-name}-lessons.md          ← Retrospective patterns after a sprint completes
+```
+
+### `qa/memory/INDEX.md` — Required
+
+The `INDEX.md` is the **gate** that the agent reads before loading any other memory file. Its purpose is to let the agent load only what is relevant to the current task, rather than loading all files.
+
+```markdown
+# Memory Index — {PROJECT_NAME}
+
+| File | Topic | When to load |
+|---|---|---|
+| playwright-blazor-wasm-patterns.md | Blazor/Radzen DOM patterns | Any Playwright automation task |
+| sprint4-discovery.md | DOM quirks for BusinessPartner module | Sprint 4 automation only |
+| sprint3-lessons.md | Patterns from Sprint 3 | Reference when working on similar modules |
+```
+
+**Rules for `qa/memory/`**:
+- Always update `INDEX.md` when adding or modifying a memory file
+- Sprint-specific discovery files (`sprint-N-discovery.md`) are for the duration of that sprint; consolidate long-term patterns into a technology-specific file afterwards
+- Never load all memory files unconditionally — always read `INDEX.md` first and select by relevance
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keber/qa-framework",
-  "version": "1.1.2",
+  "version": "1.2.0-0",
   "description": "Reusable spec-driven QA framework for IDE-agent-assisted automated testing. Installable as an npm package. Provides structure, templates, agent instructions, and optional integrations for Playwright and Azure DevOps.",
   "keywords": [
     "qa",

package/qa-framework.config.json

@@ -1,6 +1,6 @@
 {
   "$schema": "./qa-framework.config.schema.json",
-  "frameworkVersion": "1.0.0",
+  "frameworkVersion": "1.1.3",
 
   "project": {
     "name": "{{PROJECT_NAME}}",

package/scripts/init.js

@@ -79,11 +79,16 @@ process.stderr.write(`[qa-framework/init] Using config source: ${configSource}\n
 const topLevelFolders = [
   '00-guides',
   '00-standards',
-  '05-test-plans',
+  '01-specifications',
+  '02-test-plans',
+  '03-test-cases',
+  '04-test-data',
+  '05-test-execution',
   '06-defects/open',
   '06-defects/resolved',
   '07-automation/e2e',
   '08-azure-integration',
+  'memory',
 ];
 
 for (const folder of topLevelFolders) {
@@ -92,12 +97,47 @@ for (const folder of topLevelFolders) {
   console.log(`  [created] ${path.relative(cwd, fullPath)}/`);
 }
 
+// --- qa/README.md ---
+const qaReadmeTemplate = path.resolve(__dirname, '..', 'templates', 'qa-readme.md');
+if (fs.existsSync(qaReadmeTemplate)) {
+  let readmeContent = fs.readFileSync(qaReadmeTemplate, 'utf8');
+  readmeContent = readmeContent
+    .replace(/\{PROJECT_DISPLAY_NAME\}/g, config.project?.displayName ?? config.project?.name ?? 'Project')
+    .replace(/\{VERSION\}/g, config.frameworkVersion ?? '1.0.0')
+    .replace(/\{LANGUAGE\}/g, config.conventions?.language ?? 'en')
+    .replace(/\{QA_BASE_URL\}/g, config.project?.qaBaseUrl ?? '<QA_BASE_URL>');
+  writeIfMissing(path.join(qaRoot, 'README.md'), readmeContent);
+}
+
+// --- qa/memory/INDEX.md ---
+const memoryDir = path.join(qaRoot, 'memory');
+writeIfMissing(path.join(memoryDir, 'INDEX.md'),
+`# Memory Index — ${config.project?.displayName ?? config.project?.name ?? 'Project'}
+
+> The agent reads this file first before loading any memory file.
+> Add a row here whenever you create or update a file in this directory.
+
+| File | Topic | When to load |
+|---|---|---|
+
+_No memory files yet. Add files to this directory and register them above._
+`);
+
 // --- Standards placeholder ---
 const stdDir = path.join(qaRoot, '00-standards');
 writeIfMissing(path.join(stdDir, 'naming-conventions.md'), `# Naming Conventions\n\n> Fill in per your project. See keber/qa-framework docs/spec-driven-philosophy.md.\n`);
 writeIfMissing(path.join(stdDir, 'bug-report-template.md'), fs.readFileSync(
   path.resolve(__dirname, '..', 'templates', 'defect-report.md'), 'utf8'
 ));
+writeIfMissing(path.join(stdDir, 'test-case-template.md'), fs.readFileSync(
+  path.resolve(__dirname, '..', 'templates', 'test-case.md'), 'utf8'
+));
+writeIfMissing(path.join(stdDir, 'execution-report-template.md'), fs.readFileSync(
+  path.resolve(__dirname, '..', 'templates', 'execution-report.md'), 'utf8'
+));
+writeIfMissing(path.join(stdDir, 'test-data-guidelines.md'), fs.readFileSync(
+  path.resolve(__dirname, '..', 'templates', 'test-data-guidelines.md'), 'utf8'
+));
 
 // --- Per-module folders ---
 const modules = config.modules ?? [];
@@ -247,11 +287,19 @@ This project uses \`@keber/qa-framework\` v${config.frameworkVersion ?? '1.0.0'}
 
 ## Agent behavior rules
 
-1. Before performing any QA task, read the relevant instruction file from \`qa/00-guides/\`
+0. **On every conversation start:** check if \`qa/AGENT-NEXT-STEPS.md\` exists. If it does, read it and complete its steps before anything else.
+1. Before performing any QA task, read the relevant instruction file from \`qa/00-guides/\`. For project context, read \`qa/memory/INDEX.md\` if it exists, then load only the memory files relevant to the current task — do not load all memory files unconditionally.
 2. Always save artifacts in the correct \`qa/\` subfolder - refer to \`qa/QA-STRUCTURE-GUIDE.md\`
 3. Never hardcode credentials - always use env vars and \`<PLACEHOLDER>\` in documentation
 4. Follow the naming conventions in \`qa/00-standards/naming-conventions.md\`
-5. Project QA config is at \`qa/qa-framework.config.json\`
+5. Read previous test suites code in \`qa/07-automation/e2e/tests/\` if available before writing new automation to maintain consistency in style and approach
+6. Project QA config is at \`qa/qa-framework.config.json\`
+7. Save learnings in \`qa/memory/\` with proper naming and metadata. Always update \`qa/memory/INDEX.md\` after adding or updating any memory file.
+8. **On module/sprint completion** (all TCs passing): (1) update the module status row in \`qa/README.md\`; (2) move the completed sprint checklist from \`AGENT-NEXT-STEPS.md\` to the \`## Sprint History\` section of \`qa/README.md\`; (3) trim \`AGENT-NEXT-STEPS.md\` so it contains only the next sprint — never let it accumulate more than one active sprint.
+
+## Formatting rules for generated content
+1. Generate the output in \`UTF-8\` encoding without BOM (\`UTF-8\`, no signature).
+2. Ensure the raw output is \`UTF-8\` encoded with no \`EF BB BF\` bytes at the beginning.
 
 ## Available agent instructions
 
@@ -265,16 +313,49 @@ This project uses \`@keber/qa-framework\` v${config.frameworkVersion ?? '1.0.0'}
 | Stabilize failing tests | \`qa/00-guides/AGENT-INSTRUCTIONS-TEST-STABILIZATION.md\` |
 | Sync with Azure DevOps | \`qa/00-guides/AGENT-INSTRUCTIONS-ADO-INTEGRATION.md\` |
 | Maintenance after changes | \`qa/00-guides/AGENT-INSTRUCTIONS-MAINTENANCE.md\` |
+
+## Project KB
+1. \`qa/README.md\`          — The Living Index: module status, sprint history, blockers, quick-start commands.
+2. \`qa/memory/INDEX.md\`    — Index of all memory files; load this before selecting which files to read.
 `;
 writeIfMissing(copilotInstrPath, copilotInstrContent);
 
-process.stderr.write('\n[qa-framework/init] ✅ QA framework scaffold complete!\n');
-process.stderr.write('\nNext steps for the agent:\n');
-process.stderr.write('  1. If ADO integration is needed, run: npm install @keber/ado-qa\n');
-process.stderr.write('  2. If Playwright automation is needed, run: npm install @playwright/test\n');
-process.stderr.write('  3. Edit qa/qa-framework.config.json - add your project modules\n');
-process.stderr.write('  4. Copy qa/07-automation/.env.example -> qa/07-automation/.env and fill in credentials\n');
-process.stderr.write('  5. Add qa/07-automation/.env and qa/07-automation/.auth/ to .gitignore\n');
+// --- AGENT-NEXT-STEPS.md — readable by the agent after install ---
+const nextStepsContent = `# ✅ @keber/qa-framework installed successfully
+
+> This file was generated automatically by the postinstall script.
+> Read it and follow the steps below, then delete this file.
+
+## What was scaffolded
+
+- \`qa/\` folder structure with spec templates and agent instructions
+- \`.github/copilot-instructions.md\` with QA agent behavior rules
+
+## Required next steps
+
+### 1. Configure your project modules
+Edit \`qa/qa-framework.config.json\` and add your project modules under the \`"modules"\` array.
+
+### 2. Optional integrations
+
+**Azure DevOps integration:**
+\`\`\`bash
+npm install @keber/ado-qa
+\`\`\`
+
+**Playwright automation:**
+\`\`\`bash
+npm install @playwright/test
+cd qa/07-automation && npm install && npx playwright install chromium
+\`\`\`
+
+### 3. Credentials
+- Copy \`qa/07-automation/.env.example\` → \`qa/07-automation/.env\` and fill in credentials
+- Add \`qa/07-automation/.env\` and \`qa/07-automation/.auth/\` to \`.gitignore\`
+`;
+const nextStepsPath = path.join(qaRoot, 'AGENT-NEXT-STEPS.md');
+fs.writeFileSync(nextStepsPath, nextStepsContent, 'utf8');
+console.log(`  [created] ${path.relative(cwd, nextStepsPath)}`);
 
 // -----------------------------------------------------------------------
 // Helpers

package/templates/agent-next-steps.md

@@ -0,0 +1,58 @@
+# AGENT-NEXT-STEPS — {PROJECT_NAME}
+
+> **Sprint activo: Sprint {N} — {SPRINT_NAME}**
+> Lee este archivo primero. Lee los archivos referenciados solo cuando la tarea lo requiera.
+
+---
+
+## Estado del módulo
+
+| Módulo / Submódulo | Specs | Plan | Auto | Estado |
+|---|---|---|---|---|
+| {MODULE_NAME} / {SUBMODULE_NAME} | ✅ | ✅ | ⬜ | Sprint {N} activo |
+
+> Actualizar esta tabla cuando un sprint se complete. Historial de sprints completados → `qa/README.md ## Sprint History`.
+
+---
+
+## Sprint {N} — Tareas pendientes
+
+- [ ] {Tarea 1}
+- [ ] {Tarea 2}
+- [ ] {Tarea 3}
+- [ ] Actualizar `qa/README.md` (fila del módulo + Sprint History)
+- [ ] Trim este archivo: dejar solo el sprint siguiente
+
+**Precondiciones**: {Dependencias de datos o módulos previos, si aplica}
+
+**Notas específicas**: {Quirks del DOM, rutas, selectores problemáticos conocidos — o eliminar esta línea}
+→ Si las notas son extensas, guardarlas en `qa/memory/{sprint-name}-discovery.md` y referenciar aquí.
+
+---
+
+## Contexto obligatorio antes de codificar
+
+- Patrones del proyecto: `qa/memory/INDEX.md` → cargar solo los archivos relevantes
+- Referencia de estilo: `qa/07-automation/e2e/tests/{module}/` (leer suite existente más reciente)
+
+---
+
+## Sprints siguientes (solo referencia — sin checklists)
+
+- **Sprint {N+1}**: {Descripción breve — qué módulo/submódulo}
+- **Sprint {N+2}**: {Descripción breve}
+
+---
+
+<!-- ═══════════════════════════════════════════════════════════════════
+  REGLAS DE MANTENIMIENTO DE ESTE ARCHIVO (para el agente)
+  ——————————————————————————————————————————————————————————————————
+  1. MÁXIMO UN SPRINT ACTIVO. Cuando un sprint se completa:
+       a. Mover su checklist al README.md bajo ## Sprint History
+       b. Borrar esa sección de este archivo
+       c. Promover el siguiente sprint a "activo"
+  2. NO repetir instrucciones permanentes que ya estén en copilot-instructions.md.
+  3. Los detalles técnicos (DOM, patrones) van en qa/memory/, no aquí.
+  4. Los sprints "siguientes" son bullets de 1 línea, sin checklists.
+  Este archivo es una cola de trabajo. No es un log ni una bitácora.
+  ══════════════════════════════════════════════════════════════════ -->

package/templates/qa-readme.md

@@ -0,0 +1,86 @@
+# QA — {PROJECT_DISPLAY_NAME}
+
+> Framework: `@keber/qa-framework` v{VERSION}
+> Language: {LANGUAGE} | Base URL: `{QA_BASE_URL}`
+
+---
+
+## Module Status
+
+| Module | Submodule | TCs Total | TCs Automated | Plan | ADO Suite | Status | Last Run |
+|---|---|---|---|---|---|---|---|
+| {MODULE_NAME} | {SUBMODULE_NAME} | — | — | ⬜ | — | 🔲 Not started | — |
+
+**Legend**: ✅ Done · ⚠️ Partial · 🔲 Not started · ⛔ Blocked
+
+---
+
+## Quick-Start Commands
+
+```bash
+# Run all automated tests
+cd qa/07-automation
+npx playwright test
+
+# Run a specific module
+npx playwright test tests/{module-folder}/
+
+# Run with UI (debug mode)
+npx playwright test --ui
+
+# Generate HTML report
+npx playwright show-report
+
+# Re-run only failed tests
+npx playwright test --last-failed
+```
+
+> Set credentials in `qa/07-automation/.env` (copy from `.env.example`).
+
+---
+
+## Active Blockers
+
+| ID | Description | Affects | Opened | Status |
+|---|---|---|---|---|
+| — | No active blockers | — | — | — |
+
+---
+
+## Last Execution
+
+| Date | Suite | Pass | Skip | Fail | Duration | Report |
+|---|---|---|---|---|---|---|
+| — | — | — | — | — | — | — |
+
+---
+
+## Sprint History
+
+<!-- Completed sprint checklists are moved here from AGENT-NEXT-STEPS.md -->
+<!-- Format per sprint: -->
+<!--
+### Sprint N — {SPRINT_NAME} ({YYYY-MM-DD})
+
+**Submodules**: {list}
+**TCs automated**: {N} P0 + {M} P1
+**Execution report**: `qa/05-test-execution/automated/{date-slug}.md`
+
+Checklist (completed):
+- [x] {Task 1}
+- [x] {Task 2}
+-->
+
+_No sprints completed yet._
+
+---
+
+## Resources
+
+| Resource | Link |
+|---|---|
+| QA Structure Guide | `qa/QA-STRUCTURE-GUIDE.md` |
+| Naming Conventions | `qa/00-standards/naming-conventions.md` |
+| Memory Index | `qa/memory/INDEX.md` |
+| Agent Next Steps | `qa/AGENT-NEXT-STEPS.md` |
+| Automation Config | `qa/07-automation/playwright.config.ts` |

package/templates/test-data-guidelines.md

@@ -0,0 +1,130 @@
+# Test Data Guidelines
+
+> Reference: `qa/04-test-data/`  
+> All test data definitions must follow these rules. No exceptions for credentials.
+
+---
+
+## Rules
+
+### 1. Never hardcode credentials
+
+All user emails, passwords, API keys, and tokens must come from environment variables.
+
+```typescript
+// ✅ CORRECT
+const email    = process.env.QA_USER_EMAIL!;
+const password = process.env.QA_USER_PASSWORD!;
+
+// ❌ WRONG — never commit credentials
+const email    = 'admin@example.com';
+const password = 'secret123';
+```
+
+Document env var names in `qa/04-test-data/users.md`. Use `<PLACEHOLDER>` for values in all documentation.
+
+### 2. Use EXEC_IDX for unique values per run
+
+Never create records with static names — they collide between runs and can leave leftover data.
+
+```typescript
+const EXEC_IDX = Math.floor(Date.now() / 60_000) % 100_000;
+
+// Names / codes
+const name = `Test-Entity-${EXEC_IDX}`;
+
+// Future-safe dates (year 2120+ avoids real production data overlap)
+const year  = 2120 + (EXEC_IDX % 10);
+const month = String((EXEC_IDX % 12) + 1).padStart(2, '0');
+const day   = String((EXEC_IDX % 28) + 1).padStart(2, '0');
+const date  = `${year}-${month}-${day}`;
+```
+
+### 3. Provision in `beforeAll`, not `beforeEach`
+
+Create required records once per suite, not once per test. Each test that **consumes** a record needs its own provisioned record — never share a single record among multiple tests.
+
+```typescript
+test.beforeAll(async ({ browser }) => {
+  const page = await browser.newPage();
+  // If 3 tests each need 1 record, create 3:
+  for (let i = 0; i < 3; i++) {
+    await createEntity(page, `Record-${EXEC_IDX}-${i}`);
+  }
+  await page.close();
+});
+```
+
+### 4. Seed scripts go in `04-test-data/seeders/`
+
+Complex setup that cannot be done via the UI goes in a seeder script, not inside a spec file.
+
+```
+qa/04-test-data/
+├── users.md          ← Role catalog + env var names (no real values)
+├── fixtures/         ← Static JSON/Markdown for reference data
+├── factories/        ← Dynamic data generation patterns
+└── seeders/          ← DB/API seed scripts for complex prerequisites
+```
+
+### 5. Add `.env` and `.auth/` to `.gitignore`
+
+```
+qa/07-automation/.env
+qa/07-automation/.auth/
+```
+
+The `.env.example` file (committed) lists all required keys with `<PLACEHOLDER>` as the value.
+
+---
+
+## User Table Format (`04-test-data/users.md`)
+
+```markdown
+| Role | Env var (email) | Env var (password) | Permissions |
+|---|---|---|---|
+| Admin | QA_ADMIN_EMAIL | QA_ADMIN_PASSWORD | Full access |
+| Read-only | QA_READONLY_EMAIL | QA_READONLY_PASSWORD | View only |
+```
+
+---
+
+## Fixture Files (`04-test-data/fixtures/`)
+
+Use Markdown tables or JSON for static reference data that tests depend on (catalogs, option lists, etc.).
+
+```markdown
+# fixtures/catalogs.md
+## Labor Types
+| Code | Name |
+|---|---|
+| LT-01 | Consulting |
+| LT-02 | Development |
+```
+
+Reference fixtures in specs via `import` (JSON) or inline expectations matching the fixture values.
+
+---
+
+## Factory Pattern (`04-test-data/factories/`)
+
+Document how to generate complex data shapes needed by multiple tests:
+
+```typescript
+// factories/supplier.ts
+export function buildSupplier(idx: number) {
+  return {
+    name:  `Supplier-${idx}`,
+    rut:   `${76_000_000 + idx}-0`,
+    email: `supplier-${idx}@test.example`,
+  };
+}
+```
+
+---
+
+## On test teardown
+
+Do **not** delete test data after each run unless the test explicitly requires a clean state. Leftover data from old EXEC_IDX values does not affect subsequent runs because EXEC_IDX generates distinct names.
+
+Exception: if the system enforces uniqueness on a field that EXEC_IDX cannot make unique (e.g., a singleton config), document the teardown strategy in `04-test-data/seeders/`.