@pageai/ralph-loop 1.0.0

package/.agent/skills/vitest-best-practices/references/aaa-pattern.md

@@ -0,0 +1,260 @@
+# 1.2 AAA Pattern
+
+Structure tests as **Arrange**, **Act**, **Assert** for maximum clarity and readability.
+
+## What is AAA?
+
+- **Arrange**: Set up the test data, dependencies, and preconditions
+- **Act**: Execute the code under test
+- **Assert**: Verify the expected outcome
+
+This pattern makes tests instantly understandable by separating setup, execution, and verification.
+
+## Basic AAA Structure
+
+**❌ Incorrect: mixed arrange/act/assert**
+```ts
+it('should return the default value for an unknown property', () => {
+  const defaultColor: Color = [128, 128, 128, 155];
+  const colorLookup = lookup(colorTable, defaultVal(defaultColor));
+  const actual = colorLookup('UNKNOWN');
+  expect(actual).toEqual(defaultColor);
+
+  // Another test mixed in!
+  const result2 = colorLookup('ANOTHER');
+  expect(result2).toEqual(defaultColor);
+});
+```
+
+**✅ Correct: clear AAA structure with comments**
+```ts
+it('should return the default value for an unknown property', () => {
+  // Arrange
+  const defaultColor: Color = [128, 128, 128, 155];
+  const colorLookup = lookup(colorTable, defaultVal(defaultColor));
+
+  // Act
+  const actual = colorLookup('UNKNOWN');
+
+  // Assert
+  expect(actual).toEqual(defaultColor);
+});
+```
+*Why?* Without clear separation and with multiple behaviors tested together, it's hard to understand what's being tested and why a test fails.
+
+## Blank Lines for Separation
+
+Use blank lines between AAA sections even without comments for simple tests.
+
+**❌ Incorrect: no visual separation**
+```ts
+it('should calculate total price with tax', () => {
+  const cart = new ShoppingCart();
+  cart.addItem({ name: 'Widget', price: 100 });
+  const total = cart.calculateTotal(0.08);
+  expect(total).toEqual(108);
+});
+```
+
+**✅ Correct: visual separation with blank lines**
+```ts
+it('should calculate total price with tax', () => {
+  const cart = new ShoppingCart();
+  cart.addItem({ name: 'Widget', price: 100 });
+
+  const total = cart.calculateTotal(0.08);
+
+  expect(total).toEqual(108);
+});
+```
+*Why?* Without visual separation, it's harder to quickly identify where setup ends and the actual test logic begins.
+
+## Multiple Assertions for Same Behavior
+
+Multiple assertions are OK when they verify different aspects of the **same behavior**.
+
+**❌ Incorrect: testing multiple unrelated behaviors**
+```ts
+it('should handle user operations', () => {
+  // Testing creation
+  const user = createUser({ email: 'test@example.com' });
+  expect(user.email).toEqual('test@example.com');
+
+  // Testing update (different behavior!)
+  updateUser(user.id, { name: 'Updated' });
+  expect(user.name).toEqual('Updated');
+
+  // Testing deletion (different behavior!)
+  deleteUser(user.id);
+  expect(getUser(user.id)).toBeNull();
+});
+```
+
+**✅ Correct: multiple assertions for one behavior**
+```ts
+it('should create user with all required fields', () => {
+  // Arrange
+  const userData = { email: 'test@example.com', name: 'Test User' };
+
+  // Act
+  const user = createUser(userData);
+
+  // Assert
+  expect(user.email).toEqual('test@example.com');
+  expect(user.name).toEqual('Test User');
+  expect(user.id).toBeDefined();
+  expect(user.createdAt).toBeInstanceOf(Date);
+});
+```
+*Why?* Each test should verify one behavior. Split this into three separate tests: creation, update, and deletion.
+
+## Avoid Logic in Tests
+
+Keep the AAA sections simple - avoid conditional logic, loops, or complex calculations.
+
+**❌ Incorrect: complex logic in test**
+```ts
+it('should filter active users', () => {
+  const users = generateUsers(100); // Hidden complexity
+  const userService = new UserService(users);
+  const activeUsers = userService.getActiveUsers();
+
+  // Complex verification logic
+  let count = 0;
+  for (const user of users) {
+    if (user.active) {
+      expect(activeUsers).toContain(user);
+      count++;
+    }
+  }
+  expect(activeUsers).toHaveLength(count);
+});
+```
+
+**✅ Correct: straightforward test logic**
+```ts
+it('should filter active users', () => {
+  // Arrange
+  const users = [
+    { id: 1, name: 'Alice', active: true },
+    { id: 2, name: 'Bob', active: false },
+    { id: 3, name: 'Charlie', active: true },
+  ];
+  const userService = new UserService(users);
+
+  // Act
+  const activeUsers = userService.getActiveUsers();
+
+  // Assert
+  expect(activeUsers).toHaveLength(2);
+  expect(activeUsers[0].name).toEqual('Alice');
+  expect(activeUsers[1].name).toEqual('Charlie');
+});
+```
+*Why?* If the test has bugs, you won't know if the test or the code is wrong. Keep tests simple and obvious.
+
+## Complex Arrange Sections
+
+For complex setup, extract to helper functions or factories.
+
+**❌ Incorrect: complex setup in test**
+```ts
+it('should apply discount to orders over $50', () => {
+  // Arrange - too much going on!
+  const order = new Order();
+  const items = [];
+  for (let i = 0; i < 10; i++) {
+    const item = {
+      id: i,
+      name: `Item ${i}`,
+      price: 10 * i,
+      category: i % 2 === 0 ? 'even' : 'odd',
+      taxable: i > 5,
+    };
+    items.push(item);
+    order.addItem(item);
+  }
+  const discountService = new DiscountService();
+
+  // Act
+  const discountedTotal = discountService.applyDiscount(order);
+
+  // Assert
+  expect(discountedTotal).toBeLessThan(order.total);
+});
+```
+
+**✅ Correct: extracted setup helper**
+```ts
+function createTestOrder(items: number = 3): Order {
+  const order = new Order();
+  for (let i = 0; i < items; i++) {
+    order.addItem({ id: i, name: `Item ${i}`, price: 10 * i });
+  }
+  return order;
+}
+
+it('should apply discount to orders over $50', () => {
+  // Arrange
+  const order = createTestOrder(10);
+  const discountService = new DiscountService();
+
+  // Act
+  const discountedTotal = discountService.applyDiscount(order);
+
+  // Assert
+  expect(discountedTotal).toBeLessThan(order.total);
+  expect(discountService.discountApplied).toEqual(0.1);
+});
+```
+*Why?* Complex setup obscures the test's purpose. Extract to helper functions or test-utils.
+
+## Async/Await with AAA
+
+AAA works perfectly with async tests - just add await in the Act section.
+
+**❌ Incorrect: mixing setup with async calls**
+```ts
+it('should fetch user from API', async () => {
+  const userId = 'user-123';
+  const apiClient = new ApiClient();
+  const user = await apiClient.getUser(userId); // Act hidden in middle
+  const profile = await apiClient.getProfile(userId); // More acts!
+  expect(user.id).toEqual(userId);
+  expect(profile.userId).toEqual(userId);
+});
+```
+
+**✅ Correct: async AAA pattern**
+```ts
+it('should fetch user from API', async () => {
+  // Arrange
+  const userId = 'user-123';
+  const apiClient = new ApiClient();
+
+  // Act
+  const user = await apiClient.getUser(userId);
+
+  // Assert
+  expect(user.id).toEqual(userId);
+  expect(user.name).toBeDefined();
+});
+```
+*Why?* Multiple async operations without clear separation make it unclear what's being tested.
+
+## When to Omit AAA Comments
+
+For very simple tests, AAA comments can be omitted if blank lines provide sufficient clarity.
+
+**✅ Correct: simple test without AAA comments**
+```ts
+it('should add two numbers', () => {
+  const calculator = new Calculator();
+
+  const result = calculator.add(2, 3);
+
+  expect(result).toEqual(5);
+});
+```
+
+However, **when in doubt, include the comments**. They never hurt and help onboarding developers understand your test structure.

package/.agent/skills/vitest-best-practices/references/assertions.md

@@ -0,0 +1,393 @@
+# 1.5 Assertions
+
+Use strict, precise assertions that verify exact behavior. Loose assertions can pass even when code is wrong.
+
+## Equality Assertions
+
+Prefer `toEqual` over `toBe` for objects and arrays. Use `toStrictEqual` when you need to verify undefined properties.
+
+**✅ Correct: toEqual for objects**
+```ts
+it('should return user object with correct properties', () => {
+  const user = createUser({ name: 'John', email: 'john@example.com' });
+
+  expect(user).toEqual({
+    name: 'John',
+    email: 'john@example.com',
+    id: expect.any(String),
+    createdAt: expect.any(Date),
+  });
+});
+```
+
+**❌ Incorrect: toBe for objects**
+```ts
+it('should return user object', () => {
+  const user = createUser({ name: 'John' });
+  expect(user).toBe({ name: 'John' }); // Always fails - different references!
+});
+```
+*Why?* `toBe` uses `Object.is()` reference equality. For objects/arrays, use `toEqual`.
+
+## toEqual vs toStrictEqual
+
+Use `toStrictEqual` when you need to verify that undefined properties don't exist.
+
+**✅ Correct: toStrictEqual catches undefined properties**
+```ts
+it('should not include undefined properties', () => {
+  const user = { name: 'John', email: 'john@example.com' };
+
+  expect(user).toStrictEqual({ name: 'John', email: 'john@example.com' });
+});
+```
+
+**⚠️ Potential issue: toEqual ignores undefined**
+```ts
+it('may not catch unexpected undefined', () => {
+  const user = { name: 'John', email: undefined };
+
+  // This passes with toEqual!
+  expect(user).toEqual({ name: 'John' });
+
+  // This fails with toStrictEqual (better)
+  expect(user).toStrictEqual({ name: 'John' }); // Fails - email is undefined
+});
+```
+
+## Primitives: toBe vs toEqual
+
+For primitives (numbers, strings, booleans), both work, but `toBe` is more semantically correct.
+
+**✅ Correct: toBe for primitives**
+```ts
+expect(count).toBe(5);
+expect(name).toBe('John');
+expect(isValid).toBe(true);
+```
+
+**✅ Also correct but less semantic: toEqual for primitives**
+```ts
+expect(count).toEqual(5); // Works but toBe is clearer for primitives
+```
+
+## Avoid Loose Assertions
+
+Don't use fuzzy matchers when you can be precise.
+
+**❌ Incorrect: loose assertion**
+```ts
+it('should return user data', () => {
+  const result = fetchUser('123');
+  expect(result).toContain('john'); // Too vague!
+});
+```
+
+**✅ Correct: precise assertion**
+```ts
+it('should return user with email', () => {
+  const result = fetchUser('123');
+  expect(result).toEqual({
+    id: '123',
+    name: 'John Doe',
+    email: 'john@example.com',
+  });
+});
+```
+
+## Array Assertions
+
+Use specific array matchers for clarity.
+
+**✅ Correct: specific array matchers**
+```ts
+describe('filterActiveUsers', () => {
+  it('should return array of active users only', () => {
+    const users = [
+      { id: 1, name: 'Alice', active: true },
+      { id: 2, name: 'Bob', active: false },
+      { id: 3, name: 'Charlie', active: true },
+    ];
+
+    const result = filterActiveUsers(users);
+
+    expect(result).toHaveLength(2);
+    expect(result).toEqual([
+      { id: 1, name: 'Alice', active: true },
+      { id: 3, name: 'Charlie', active: true },
+    ]);
+  });
+
+  it('should contain specific user', () => {
+    const result = getAllUsers();
+    expect(result).toContainEqual({ id: 1, name: 'Alice', active: true });
+  });
+
+  it('should return empty array when no active users', () => {
+    const users = [{ id: 1, name: 'Bob', active: false }];
+    expect(filterActiveUsers(users)).toEqual([]);
+  });
+});
+```
+
+**❌ Incorrect: imprecise array checks**
+```ts
+it('should return users', () => {
+  const result = filterActiveUsers(users);
+  expect(result.length).toBeGreaterThan(0); // How many? Which users?
+});
+```
+
+## String Assertions
+
+Use appropriate string matchers based on what you're testing.
+
+**✅ Correct: precise string assertions**
+```ts
+describe('formatName', () => {
+  it('should return full name', () => {
+    expect(formatName('john', 'doe')).toBe('John Doe');
+  });
+
+  it('should include title when provided', () => {
+    const result = formatName('john', 'doe', 'Dr.');
+    expect(result).toBe('Dr. John Doe');
+  });
+
+  it('should match name pattern', () => {
+    const result = formatName('john', 'doe');
+    expect(result).toMatch(/^[A-Z][a-z]+ [A-Z][a-z]+$/);
+  });
+
+  it('should contain first name', () => {
+    const result = formatName('john', 'doe');
+    expect(result).toContain('John');
+  });
+});
+```
+
+**❌ Incorrect: overly loose string checks**
+```ts
+it('should format name', () => {
+  const result = formatName('john', 'doe');
+  expect(result).toBeTruthy(); // Way too vague!
+  expect(result.length).toBeGreaterThan(0); // Still vague!
+});
+```
+
+## Number Assertions
+
+Use comparison matchers for numeric ranges and boundaries.
+
+**✅ Correct: numeric matchers**
+```ts
+describe('calculateDiscount', () => {
+  it('should return positive discount', () => {
+    const discount = calculateDiscount(100, 0.1);
+    expect(discount).toBeGreaterThan(0);
+    expect(discount).toBeLessThanOrEqual(100);
+  });
+
+  it('should return exact discount amount', () => {
+    expect(calculateDiscount(100, 0.1)).toBe(10);
+  });
+
+  it('should handle floating point comparison', () => {
+    const result = calculateTax(99.99, 0.0825);
+    expect(result).toBeCloseTo(8.25, 2); // Within 2 decimal places
+  });
+});
+```
+
+## Boolean and Nullish Assertions
+
+Be explicit about boolean, null, and undefined checks.
+
+**✅ Correct: explicit boolean checks**
+```ts
+describe('isValidEmail', () => {
+  it('should return true for valid email', () => {
+    expect(isValidEmail('test@example.com')).toBe(true);
+  });
+
+  it('should return false for invalid email', () => {
+    expect(isValidEmail('invalid')).toBe(false);
+  });
+});
+
+describe('findUser', () => {
+  it('should return null when user not found', () => {
+    expect(findUser('invalid-id')).toBeNull();
+  });
+
+  it('should return undefined for missing optional field', () => {
+    const user = createUser({ name: 'John' });
+    expect(user.middleName).toBeUndefined();
+  });
+
+  it('should have defined email', () => {
+    const user = createUser({ name: 'John', email: 'john@example.com' });
+    expect(user.email).toBeDefined();
+  });
+});
+```
+
+**❌ Incorrect: loose truthy/falsy checks**
+```ts
+it('should validate email', () => {
+  expect(isValidEmail('test@example.com')).toBeTruthy(); // Could be any truthy value!
+});
+
+it('should not find user', () => {
+  expect(findUser('invalid')).toBeFalsy(); // Could be false, null, undefined, 0, etc.
+});
+```
+*Why?* `toBeTruthy`/`toBeFalsy` are too permissive. Be explicit about the expected value.
+
+## Object Property Assertions
+
+Use matchers that verify object structure and properties.
+
+**✅ Correct: object property matchers**
+```ts
+describe('createUser', () => {
+  it('should have required properties', () => {
+    const user = createUser({ name: 'John', email: 'john@example.com' });
+
+    expect(user).toHaveProperty('id');
+    expect(user).toHaveProperty('name', 'John');
+    expect(user).toHaveProperty('email', 'john@example.com');
+    expect(user).toHaveProperty('createdAt');
+  });
+
+  it('should match expected shape', () => {
+    const user = createUser({ name: 'John', email: 'john@example.com' });
+
+    expect(user).toMatchObject({
+      name: 'John',
+      email: 'john@example.com',
+    });
+    // toMatchObject allows extra properties like id, createdAt
+  });
+});
+```
+
+## Type Assertions
+
+Verify types when type checking is important.
+
+**✅ Correct: type assertions**
+```ts
+describe('parseData', () => {
+  it('should return correct types', () => {
+    const result = parseData('{"count": 5}');
+
+    expect(result.count).toEqual(expect.any(Number));
+    expect(result.timestamp).toEqual(expect.any(Date));
+    expect(result.tags).toEqual(expect.any(Array));
+  });
+
+  it('should return string array', () => {
+    const tags = getTags();
+
+    expect(tags).toEqual(expect.arrayContaining([expect.any(String)]));
+  });
+});
+```
+
+## Asymmetric Matchers
+
+Use asymmetric matchers when exact values aren't known but structure is.
+
+**✅ Correct: asymmetric matchers for dynamic values**
+```ts
+describe('createOrder', () => {
+  it('should create order with generated ID', () => {
+    const order = createOrder({ items: [{ id: 1, quantity: 2 }] });
+
+    expect(order).toEqual({
+      id: expect.stringMatching(/^order-[a-f0-9]+$/),
+      items: expect.arrayContaining([
+        expect.objectContaining({ id: 1, quantity: 2 }),
+      ]),
+      createdAt: expect.any(Date),
+      status: 'pending',
+    });
+  });
+});
+```
+
+## Negation
+
+Use `.not` to assert something is NOT true, but be specific.
+
+**✅ Correct: specific negation**
+```ts
+it('should not include deleted users', () => {
+  const users = getActiveUsers();
+
+  expect(users).not.toContainEqual(
+    expect.objectContaining({ status: 'deleted' })
+  );
+});
+
+it('should not be empty string', () => {
+  const username = generateUsername();
+  expect(username).not.toBe('');
+  expect(username.length).toBeGreaterThan(0);
+});
+```
+
+**❌ Incorrect: vague negation**
+```ts
+it('should not be wrong', () => {
+  expect(result).not.toBeFalsy(); // What IS it then?
+});
+```
+
+## Custom Error Messages
+
+Add custom messages to clarify assertion failures.
+
+**✅ Correct: custom error messages for complex assertions**
+```ts
+it('should process all items', () => {
+  const result = processItems(items);
+
+  expect(
+    result.every(item => item.processed === true),
+    'All items should have processed=true'
+  ).toBe(true);
+});
+```
+
+## Common Assertion Anti-Patterns
+
+**❌ Incorrect: no assertion**
+```ts
+it('should create user', () => {
+  createUser({ name: 'John' });
+  // No assertion! Test always passes!
+});
+```
+
+**❌ Incorrect: asserting implementation details**
+```ts
+it('should call internal helper', () => {
+  const spy = vi.spyOn(service, '_internalHelper');
+  service.publicMethod();
+  expect(spy).toHaveBeenCalled(); // Testing internal implementation
+});
+```
+*Why?* Test behavior, not implementation. Internal helpers can change without breaking public API.
+
+**❌ Incorrect: multiple unrelated assertions**
+```ts
+it('should work', () => {
+  const user = createUser({ name: 'John' });
+  expect(user.name).toBe('John');
+
+  const product = createProduct({ name: 'Widget' });
+  expect(product.name).toBe('Widget'); // Different concern - split into separate test
+});
+```