ace-test 0.6.0

data/handbook/guides/testing/vue-vitest.md

@@ -0,0 +1,236 @@
+---
+doc-type: guide
+title: Vue + Vitest Testing Guide
+purpose: Vue Vitest testing reference
+ace-docs:
+  last-updated: 2026-01-23
+  last-checked: 2026-03-21
+---
+
+# Vue + Vitest Testing Guide
+
+Quick reference for Vue component testing with Vitest, focusing on single-run execution for coding agents and CI environments.
+
+## Single-Run Commands
+
+```bash
+# Basic single run (exits immediately)
+vitest run
+
+# Run with output to file for parsing
+vitest run --reporter=json --outputFile=reports/vitest.json
+
+# Fail-fast with minimal output
+vitest run --bail=1 --silent
+
+# Run only changed files
+vitest run --changed
+
+# Run specific test files
+vitest run src/components/__tests__/LoginForm.test.js
+```
+
+## Component Testing Patterns
+
+### Basic Component Test Structure
+
+```javascript
+import { mount } from '@vue/test-utils'
+import { describe, it, expect, beforeEach } from 'vitest'
+import LoginForm from '../LoginForm.vue'
+
+describe('LoginForm', () => {
+  let wrapper
+
+  beforeEach(() => {
+    wrapper = mount(LoginForm)
+  })
+
+  it('renders login form elements', () => {
+    expect(wrapper.find('input[type="email"]').exists()).toBe(true)
+    expect(wrapper.find('input[type="password"]').exists()).toBe(true)
+    expect(wrapper.find('button[type="submit"]').exists()).toBe(true)
+  })
+
+  it('emits login event with form data', async () => {
+    await wrapper.find('input[type="email"]').setValue('test@example.com')
+    await wrapper.find('input[type="password"]').setValue('password123')
+    await wrapper.find('form').trigger('submit.prevent')
+
+    expect(wrapper.emitted('login')).toHaveLength(1)
+    expect(wrapper.emitted('login')[0][0]).toEqual({
+      email: 'test@example.com',
+      password: 'password123'
+    })
+  })
+})
+```
+
+### Testing with Composables
+
+```javascript
+import { mount } from '@vue/test-utils'
+import { vi } from 'vitest'
+import ProfileView from '../ProfileView.vue'
+
+// Mock the composable
+vi.mock('@/composables/useAuth', () => ({
+  useAuth: () => ({
+    user: { value: { email: 'test@example.com', name: 'Test User' } },
+    loading: { value: false },
+    logout: vi.fn()
+  })
+}))
+
+describe('ProfileView', () => {
+  it('displays user information', () => {
+    const wrapper = mount(ProfileView)
+    expect(wrapper.text()).toContain('test@example.com')
+    expect(wrapper.text()).toContain('Test User')
+  })
+})
+```
+
+### Testing with Router
+
+```javascript
+import { mount } from '@vue/test-utils'
+import { createRouter, createWebHistory } from 'vue-router'
+import App from '../App.vue'
+
+const router = createRouter({
+  history: createWebHistory(),
+  routes: [
+    { path: '/', component: { template: '<div>Home</div>' } },
+    { path: '/login', component: { template: '<div>Login</div>' } }
+  ]
+})
+
+describe('App with Router', () => {
+  it('navigates to login page', async () => {
+    const wrapper = mount(App, {
+      global: {
+        plugins: [router]
+      }
+    })
+
+    await router.push('/login')
+    await wrapper.vm.$nextTick()
+
+    expect(wrapper.text()).toContain('Login')
+  })
+})
+```
+
+## Configuration for Single-Run
+
+### vitest.config.js
+
+```javascript
+import { defineConfig } from 'vitest/config'
+import vue from '@vitejs/plugin-vue'
+
+export default defineConfig({
+  plugins: [vue()],
+  test: {
+    environment: 'happy-dom',
+    // For CI/automated testing
+    run: true, // Force single-run mode
+    reporters: ['default', 'json'],
+    outputFile: {
+      json: './reports/vitest.json'
+    },
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'html', 'lcov']
+    }
+  }
+})
+```
+
+### package.json Scripts
+
+```json
+{
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest run --coverage"
+  }
+}
+```
+
+## Coding Agent Integration
+
+### Exit Code Handling
+
+```bash
+# Test success/failure based on exit code
+vitest run && echo "✅ Tests passed" || echo "❌ Tests failed"
+
+# Store exit code for processing
+vitest run
+TEST_EXIT_CODE=$?
+if [ $TEST_EXIT_CODE -eq 0 ]; then
+  echo "All tests passed"
+else
+  echo "Tests failed with code $TEST_EXIT_CODE"
+fi
+```
+
+### JSON Output Parsing
+
+```javascript
+// Parse test results from JSON output
+const results = JSON.parse(fs.readFileSync('reports/vitest.json', 'utf8'))
+
+console.log(`Tests: ${results.testResults.length}`)
+console.log(`Passed: ${results.numPassedTests}`)
+console.log(`Failed: ${results.numFailedTests}`)
+
+// Get failed test details
+const failedTests = results.testResults
+  .filter(test => test.status === 'failed')
+  .map(test => ({ name: test.name, error: test.message }))
+```
+
+## Common Pitfalls & Solutions
+
+| Issue | Solution |
+|-------|----------|
+| Tests hang in watch mode | Always use `vitest run` for automated testing |
+| Mock not applying | Ensure `vi.mock()` is called before imports |
+| Async test failures | Use proper `await` and `nextTick()` |
+| Component not rendering | Check if all required props are provided |
+| Router tests failing | Mock router or provide test router instance |
+
+## Best Practices for Automation
+
+1. **Always use `vitest run`** - Never leave tests in watch mode for CI/agents
+2. **Set explicit timeouts** - Prevent hanging tests with `--testTimeout=10000`
+3. **Use JSON reporter** - Parse structured output instead of console logs
+4. **Fail fast** - Use `--bail=1` to stop on first failure
+5. **Clean output** - Use `--silent` or `--reporter=dot` for minimal noise
+6. **Exit code validation** - Check process exit code for pass/fail status
+
+## Quick Commands Reference
+
+```bash
+# Single run with coverage
+vitest run --coverage
+
+# Run specific test pattern
+vitest run --testNamePattern="LoginForm"
+
+# Run tests for specific files
+vitest run src/components/**/*.test.js
+
+# Generate machine-readable report
+vitest run --reporter=junit --outputFile=reports/junit.xml
+
+# Minimal output for CI
+vitest run --reporter=dot --silent
+```
+
+This guide ensures your Vue + Vitest tests run deterministically and provide clear success/failure signals for coding agents and CI environments.

data/handbook/guides/testing-philosophy.g.md

@@ -0,0 +1,82 @@
+---
+doc-type: guide
+title: Testing Philosophy
+purpose: Testing philosophy and pyramid structure
+ace-docs:
+  last-updated: 2026-02-22
+  last-checked: 2026-03-21
+---
+
+# Testing Philosophy
+
+## The Testing Pyramid
+
+ACE follows a strict testing pyramid with clear IO boundaries:
+
+| Layer | Location | IO Policy | Purpose |
+|-------|----------|-----------|---------|
+| **Unit (atoms)** | `test/atoms/` | **No IO** | Test pure logic in isolation |
+| **Unit (molecules)** | `test/molecules/` | **No IO** | Test component composition |
+| **Unit (organisms)** | `test/organisms/` | **Mocked IO** | Test business logic with stubbed boundaries |
+| **Integration** | `test/integration/` | **Mocked IO** | Test CLI/API surface with stubbed externals |
+| **E2E** | `test/e2e/TS-*/scenario.yml` | **Real IO** | Validate the real system works |
+
+## IO Isolation Principle
+
+**Default: No IO in unit tests.** This means:
+
+- **No file system**: Use `MockGitRepo` or inline strings, not `File.read`
+- **No network**: Use `WebMock` stubs, not real HTTP calls
+- **No subprocesses**: Use method stubs, not `Open3.capture3`
+- **No sleep**: Stub `Kernel.sleep` in retry logic
+
+**Why?**
+- Tests run in parallel safely
+- Tests are fast (<10ms for atoms)
+- Tests are deterministic (no flaky failures)
+- CI doesn't need special setup
+
+## When Real IO is Allowed
+
+Real IO belongs in **E2E tests only** (`test/e2e/TS-*/`):
+
+- Executed by an agent, not the test runner
+- Verify the full system works end-to-end
+- Run infrequently (on-demand, not every commit)
+- Document real tool requirements (standardrb, rubocop, etc.)
+
+See `/ace-e2e-run` workflow for execution.
+
+## Core Principles
+
+### 1. Test-Driven Development
+
+Writing tests first drives design and ensures testability. Follow the Red-Green-Refactor cycle:
+
+1. **Red**: Write a failing test that defines the desired outcome
+2. **Green**: Write the minimum code to make the test pass
+3. **Refactor**: Improve code design while keeping tests green
+
+### 2. Isolation
+
+- Unit tests should mock dependencies to test the unit in isolation
+- Ensure tests clean up after themselves (reset state, delete created files/records)
+- Tests must be independent and runnable in any order
+
+### 3. Determinism
+
+- Avoid flaky tests (tests that pass sometimes and fail others without code changes)
+- Address sources of flakiness (timing issues, race conditions, external dependencies)
+- Tests should produce the same result every run
+
+### 4. Clarity
+
+- Use descriptive names for test files, contexts, and individual tests
+- Follow the Arrange-Act-Assert pattern
+- Keep tests focused on a single behavior or requirement
+
+## Related Guides
+
+- [Test Organization](guide://test-organization) - Directory structure and naming
+- [Mocking Patterns](guide://mocking-patterns) - How to isolate tests
+- [Testing TDD Cycle](guide://testing-tdd-cycle) - Implementing the task cycle

data/handbook/guides/testing-strategy.g.md

@@ -0,0 +1,151 @@
+---
+doc-type: guide
+title: "Testing Strategy: The Fast and Slow Loops"
+purpose: Define the ACE testing strategy with fast loop (unit/integration) and slow loop (E2E)
+ace-docs:
+  last-updated: 2026-02-19
+  last-checked: 2026-03-21
+---
+
+# Testing Strategy: The Fast and Slow Loops
+
+This guide defines the ACE strategy for maintaining a high-performance, high-confidence test suite. We divide testing into two distinct loops: the **Fast Loop** (immediate feedback) and the **Slow Loop** (comprehensive validation).
+
+## Core Philosophy
+
+1.  **Fast Loop must be FAST (< 10s total)**: If unit tests are slow, developers stop running them.
+2.  **Slow Loop must be SAFE**: E2E tests run real commands and modify state; they must be sandboxed.
+3.  **Stub the Boundary**: Never let a unit test leak a subprocess call or file I/O.
+4.  **Test Behavior, Not Mocks**: Verify the *outcome* of logic, not just that a method was called.
+
+## The Test Pyramid
+
+| Layer | Scope | Target Speed | I/O | Strategy |
+|-------|-------|--------------|-----|----------|
+| **Unit** (Atoms) | Single Method/Class | < 10ms / test | **Forbidden** | Pure functions. Mock *all* collaborators. |
+| **Integration** (Molecules) | Component Interaction | < 100ms / test | **Stubbed** | Test wiring. Stub APIs/Shell/FS. |
+| **E2E** (Systems) | Full Workflow | Seconds/Minutes | **Real** | Real CLI execution. Sandboxed FS. |
+
+> **Note**: Target speeds are ideal goals. The `verify-test-suite` workflow uses relaxed thresholds for warnings (atoms >50ms, molecules >100ms) to catch tests drifting toward I/O leaks before they become critical.
+
+---
+
+## 1. The Fast Loop (Unit & Integration)
+
+**Goal**: Validate logic correctness instantly.
+
+### Rules of Engagement
+-   **No Subprocesses**: Never call `system`, `Open3`, or backticks.
+-   **No Network**: Never make HTTP requests.
+-   **In-Memory FS**: Use `FakeFS` or temporary directories only if absolutely necessary (prefer mocking `File`).
+
+### Effective Mocking: "Stub the Boundary"
+Don't just stub the inner implementation; stub the *check* that leads to it.
+
+**Bad** (Still triggers subprocess):
+```ruby
+# The code checks `if runner.available?` before calling `run`
+Runner.stub(:run, result) do
+  # Code calls `available?` -> triggers `system("cmd --version")` -> SLOW!
+  subject.process
+end
+```
+
+**Good** (Fast):
+```ruby
+Runner.stub(:available?, true) do # Bypass the check
+  Runner.stub(:run, result) do    # Return canned result
+    subject.process
+  end
+end
+```
+
+### Avoiding "Testing the Mock"
+-   **Stub for Data**: When you need a value to proceed (e.g., configuration, file content), use stubs.
+-   **Mock for Side Effects**: Only use `Minitest::Mock` (expectations) when the *purpose* of the method is the side effect (e.g., `Git.commit`).
+-   **Don't over-specify**: If your test breaks every time you rename a private helper, you are testing implementation, not behavior.
+
+### Maintainable Stubbing (Composite Helpers)
+Avoid deeply nested stub blocks. Use composite helpers to wrap common environmental setups.
+
+**Bad (Deep Nesting):**
+```ruby
+def test_workflow
+  mock_config do
+    mock_git do
+      mock_llm do
+        # Actual test code is buried
+      end
+    end
+  end
+end
+```
+
+**Good (Composite Helper):**
+```ruby
+def test_workflow
+  with_mock_environment(git: true, llm: true) do
+    # Clear test focus
+  end
+end
+```
+
+### Mock Hygiene (Avoiding Drift)
+Mocks simulate reality, but reality changes.
+-   **Rule**: Whenever you change behavior covered by an E2E test (reality), you MUST verify and update the corresponding Unit Test mocks (simulation).
+-   **Risk**: "Mock Drift" leads to green unit tests that fail in production.
+
+---
+
+## 2. The Slow Loop (E2E)
+
+**Goal**: Validate system coherence and real-world functionality.
+
+### Rules of Engagement
+-   **Real Binaries**: Execute the actual `ace-*` CLI tools.
+-   **Sandboxing**: Run in a temporary directory. Clean up after yourself.
+-   **Critical Paths**: Focus on happy paths and critical error cases. Don't test every edge case (leave that to unit tests).
+
+### E2E Test Structure (TS-format)
+We use directory-based test scenarios with `scenario.yml` and `TC-*.tc.md` files for E2E to ensure they double as documentation.
+
+```
+TS-FEATURE-001-task-creation/
+    scenario.yml          # Metadata + setup
+    TC-001-create.tc.md   # Test case with steps + assertions
+    fixtures/             # Shared test data
+```
+
+---
+
+## 3. The "Test Planner" & "Test Writer" Roles
+
+When creating tests, separate the concerns:
+
+### 🎩 The Test Planner
+Decides **WHAT** and **WHERE** to test.
+-   *"This logic handles a git conflict. It's complex logic -> **Unit Test** with mocked git output."*
+-   *"This command wires up the search tool to the LLM. -> **Integration Test** with stubbed LLM."*
+-   *"This workflow creates a PR and comments on it. -> **E2E Test**."*
+
+### ✍️ The Test Writer
+Implements the test efficiently.
+-   Uses `ace-test --profile` to ensure speed.
+-   Writes proper setup/teardown.
+-   Ensures assertions are meaningful.
+
+---
+
+## 4. Maintenance & Profiling
+
+### The 100ms Rule
+Any unit/integration test taking > 100ms is a bug.
+-   **Cause**: Likely a hidden I/O call (subprocess, file system).
+-   **Fix**: Profile, find the leak, and **Stub the Boundary**.
+
+### Periodic Verification
+Run the suite with profiling regularly:
+```bash
+ace-test --profile 10
+```
+If "fast" tests appear in the top 10 slow list, investigate immediately.

data/handbook/guides/testing-tdd-cycle.g.md

@@ -0,0 +1,146 @@
+---
+doc-type: guide
+title: Implementing the Task Cycle
+purpose: Task cycle implementation
+ace-docs:
+  last-updated: 2026-02-22
+  last-checked: 2026-03-21
+---
+
+# Implementing the Task Cycle
+
+## 1. Introduction
+
+This guide outlines the standard development cycle used for implementing tasks within this project. Following this cycle
+ensures consistency, promotes quality through testing, and facilitates effective collaboration, especially when working
+with AI agents. It integrates principles of Test-Driven Development (TDD) and emphasizes continuous reflection.
+
+## 2. The Core Cycle Overview
+
+The typical task implementation follows these high-level steps:
+
+1. **Start:** Understand the task and plan the approach.
+2. **Test (Red):** Write a failing test that defines the desired outcome.
+3. **Code (Green):** Write the minimum code required to make the test pass.
+4. **Refactor:** Improve the code's design while ensuring tests still pass.
+5. **Verify:** Run all checks (linters, formatters, full test suite).
+6. **Commit:** Save the changes with a clear, conventional commit message.
+7. **Reflect:** Analyze the process and capture learnings.
+8. **Update Status:** Mark the task as complete or note progress.
+
+This cycle (steps 2-4) may be repeated multiple times for a single task as functionality is built incrementally.
+
+## 3. Detailed Steps
+
+Here's a more detailed breakdown of each step, referencing relevant workflow instructions:
+
+### Step 1: Start Task (Understand & Plan)
+
+* **Goal:** Fully understand the task requirements and plan the implementation approach.
+* **Actions:**
+  * Carefully review the task description (`.md` file) including objectives, scope, and acceptance criteria.
+  * Identify relevant existing code, patterns, or documentation.
+  * Break down the task into smaller, manageable implementation steps.
+  * Outline the required tests based on acceptance criteria.
+* **Workflow:** See [`work-on-task.wf.md`](wfi://task/work)
+
+### Step 2: Write Tests (TDD - Red)
+
+* **Goal:** Define the desired behavior or functionality by writing an automated test *before* writing the
+  implementation code.
+* **Actions:**
+  * Create a new test file or add to an existing one.
+  * Write a specific test case that captures one aspect of the requirement.
+  * Ensure the test clearly describes the expected outcome.
+  * Run the test and confirm that it **fails** (this is the "Red" phase).
+* **Workflow:** See the testing section in [`work-on-task.wf.md`](wfi://task/work)
+
+### Step 3: Implement Code (TDD - Green)
+
+* **Goal:** Write the simplest, minimum amount of code necessary to make the failing test pass.
+* **Actions:**
+  * Focus *only* on satisfying the requirements of the current failing test.
+  * Avoid adding extra functionality or premature optimizations.
+  * Run the test(s) frequently until the target test passes (this is the "Green" phase).
+
+### Step 4: Refactor (TDD - Refactor)
+
+* **Goal:** Improve the design, clarity, and structure of the code *now that it works* (tests are passing).
+* **Actions:**
+  * Look for opportunities to remove duplication, improve variable names, simplify logic, or adhere better to coding
+    standards.
+  * Run tests after each small refactoring step to ensure no behavior was broken.
+* **Reference:** [Coding Standards](guide://coding-standards.g)
+
+### Step 5: Verify Locally
+
+* **Goal:** Ensure the changes integrate well and meet overall quality standards before committing.
+* **Actions:**
+  * Run the full test suite (not just the tests for the current change).
+  * Run linters and code formatters.
+  * Check test coverage if applicable.
+
+### Step 6: Commit Changes
+
+* **Goal:** Save the completed, tested, and verified changes to version control with a meaningful message.
+* **Actions:**
+  * Stage only the files related to the logical change being committed (atomic commits).
+  * Review staged changes (`git diff --staged`).
+  * **Critically review any AI-generated code before committing.**
+  * Write a commit message following the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)
+    standard.
+* **Workflow:** See [`commit.wf.md`](wfi://git/commit)
+* **Reference:** [Version Control Git Guide](guide://version-control-system-git)
+
+### Step 7: Self-Reflection
+
+* **Goal:** Analyze the completed work to capture learnings and identify potential improvements.
+* **Actions:**
+  * Review the implementation process, challenges, and successes.
+  * Update documentation (guides, ADRs, comments) if necessary.
+  * Identify any follow-up actions (e.g., refactoring needs, process improvements) and create backlog tasks if
+    needed.
+  * Log the reflection summary using the [`create-reflection-note.wf.md`](wfi://create-reflection-note) workflow.
+
+### Step 8: Update Task Status
+
+* **Goal:** Keep project tracking up-to-date.
+* **Actions:**
+  * Update the status field (e.g., to `done`) in the task's `.md` file.
+  * Move the task file to the appropriate `done` directory if applicable (refer to project management
+    specifics).
+* **Reference:** [Project Management Guide](guide://project-management.g)
+
+## 4. Key Principles & Best Practices
+
+* **Test-Driven Development:** Writing tests first drives design and ensures testability.
+* **Atomic Commits:** Each commit should represent a single, logical change.
+* **Review AI Contributions:** Treat AI-generated code with the same rigor as code from any other source. Verify its
+  correctness and adherence to standards.
+* **Incremental Progress:** Build functionality in small, testable steps.
+* **Continuous Improvement:** Use the self-reflection step to actively improve code and processes.
+
+## 5. Technology-Specific Variations
+
+While the core cycle remains the same, specific commands and tools vary by technology stack. Refer to the relevant
+sub-guide for details:
+
+* [Ruby Application](./test-driven-development-cycle/ruby-application.md)
+* [Ruby Gem](./test-driven-development-cycle/ruby-gem.md)
+* [Rust CLI](./test-driven-development-cycle/rust-cli.md)
+* [Rust→Wasm Zed Extension](./test-driven-development-cycle/rust-wasm-zed.md)
+* [TypeScript + Vue](./test-driven-development-cycle/typescript-vue.md)
+* [TypeScript + Nuxt](./test-driven-development-cycle/typescript-nuxt.md)
+* [Meta (Documentation)](./test-driven-development-cycle/meta-documentation.md)
+
+## 6. Related Documentation
+
+* **Workflow Instructions:**
+  * [`work-on-task.wf.md`](wfi://task/work) (includes testing guidance)
+  * [`commit.wf.md`](wfi://git/commit)
+  * [`save-session-context.wf.md`](wfi://save-session-context) (for saving session context)
+* **Core Guides:**
+  * [Testing Guide](./testing.g.md)
+  * [Version Control Git Guide](guide://version-control-system-git)
+  * [Coding Standards](guide://coding-standards.g)
+  * [Project Management Guide](guide://project-management.g)