@caoscompanybr/merlin 3.5.0

package/.merlin-core/skills/general/testing/SKILL.md

@@ -0,0 +1,412 @@
+---
+name: testing
+description: Testing expertise covering test strategy, unit/integration/e2e testing, mocking, coverage, and TDD
+license: Apache-2.0
+metadata:
+  author: merlin-framework
+  version: "3.0.0"
+  auto_activate: [unit-test, jest, pytest, vitest, test-coverage]
+---
+
+# Testing
+
+Expert knowledge of testing strategies, test pyramid, unit/integration/e2e testing, mocking patterns, test coverage, and Test-Driven Development (TDD).
+
+## Test Pyramid
+
+```
+        /\
+       /E2E\      <- Few, slow, expensive
+      /------\
+     /  INT   \   <- Some, moderate speed
+    /----------\
+   /    UNIT    \ <- Many, fast, cheap
+  /--------------\
+```
+
+### Distribution Guidelines
+
+- **70% Unit Tests**: Fast, isolated, test single units
+- **20% Integration Tests**: Test component interactions
+- **10% E2E Tests**: Test complete user flows
+
+## Unit Testing
+
+### JavaScript/TypeScript (Jest/Vitest)
+
+```typescript
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+
+describe("Calculator", () => {
+  let calculator: Calculator;
+
+  beforeEach(() => {
+    calculator = new Calculator();
+  });
+
+  afterEach(() => {
+    calculator.reset();
+  });
+
+  it("should add two numbers", () => {
+    const result = calculator.add(2, 3);
+    expect(result).toBe(5);
+  });
+
+  it("should throw on division by zero", () => {
+    expect(() => calculator.divide(10, 0)).toThrow("Division by zero");
+  });
+
+  it("should handle async operations", async () => {
+    const result = await calculator.asyncAdd(2, 3);
+    expect(result).resolves.toBe(5);
+  });
+});
+```
+
+### Python (pytest)
+
+```python
+import pytest
+from myapp import Calculator
+
+class TestCalculator:
+    @pytest.fixture
+    def calculator(self):
+        return Calculator()
+
+    def test_add(self, calculator):
+        result = calculator.add(2, 3)
+        assert result == 5
+
+    def test_divide_by_zero(self, calculator):
+        with pytest.raises(ValueError, match="Division by zero"):
+            calculator.divide(10, 0)
+
+    @pytest.mark.asyncio
+    async def test_async_add(self, calculator):
+        result = await calculator.async_add(2, 3)
+        assert result == 5
+
+    @pytest.mark.parametrize("a,b,expected", [
+        (2, 3, 5),
+        (0, 0, 0),
+        (-1, 1, 0),
+    ])
+    def test_add_parametrized(self, calculator, a, b, expected):
+        assert calculator.add(a, b) == expected
+```
+
+## Mocking Best Practices
+
+### Jest/Vitest Mocking
+
+```typescript
+import { vi } from "vitest";
+
+// Mock functions
+const mockCallback = vi.fn((x) => x + 1);
+mockCallback(1);
+expect(mockCallback).toHaveBeenCalledWith(1);
+expect(mockCallback).toHaveReturnedWith(2);
+
+// Mock modules
+vi.mock("./api", () => ({
+  fetchUser: vi.fn(() => Promise.resolve({ id: "1", name: "John" })),
+}));
+
+// Spy on methods
+const spy = vi.spyOn(object, "method");
+object.method("arg");
+expect(spy).toHaveBeenCalledWith("arg");
+spy.mockRestore();
+
+// Mock timers
+vi.useFakeTimers();
+setTimeout(() => callback(), 1000);
+vi.advanceTimersByTime(1000);
+expect(callback).toHaveBeenCalled();
+vi.useRealTimers();
+
+// Mock fetch
+global.fetch = vi.fn(() =>
+  Promise.resolve({
+    json: () => Promise.resolve({ data: "test" }),
+  }),
+);
+```
+
+### Python Mocking
+
+```python
+from unittest.mock import Mock, patch, MagicMock
+import pytest
+
+# Mock objects
+mock_api = Mock()
+mock_api.fetch_user.return_value = {'id': '1', 'name': 'John'}
+
+# Patch functions
+@patch('myapp.api.fetch_user')
+def test_get_user(mock_fetch):
+    mock_fetch.return_value = {'id': '1', 'name': 'John'}
+    result = get_user('1')
+    assert result['name'] == 'John'
+    mock_fetch.assert_called_once_with('1')
+
+# Context manager patching
+def test_with_patch():
+    with patch('myapp.api.fetch_user') as mock_fetch:
+        mock_fetch.return_value = {'id': '1'}
+        result = get_user('1')
+        assert result['id'] == '1'
+
+# Mock attributes
+mock = MagicMock()
+mock.method.return_value = 'result'
+mock.attribute = 'value'
+
+# Side effects
+mock.method.side_effect = [1, 2, 3]  # Returns in sequence
+mock.method.side_effect = Exception('Error')  # Raises exception
+```
+
+## Integration Testing
+
+### API Testing
+
+```typescript
+import request from "supertest";
+import { app } from "./app";
+
+describe("API Integration", () => {
+  it("should create a user", async () => {
+    const response = await request(app)
+      .post("/api/users")
+      .send({ name: "John", email: "john@test.com" })
+      .expect(201);
+
+    expect(response.body).toMatchObject({
+      name: "John",
+      email: "john@test.com",
+    });
+  });
+
+  it("should fetch users", async () => {
+    const response = await request(app).get("/api/users").expect(200);
+
+    expect(Array.isArray(response.body)).toBe(true);
+  });
+});
+```
+
+### Database Testing
+
+```python
+import pytest
+from sqlalchemy import create_engine
+from myapp.models import User, Base
+
+@pytest.fixture(scope='function')
+def db_session():
+    engine = create_engine('sqlite:///:memory:')
+    Base.metadata.create_all(engine)
+    Session = sessionmaker(bind=engine)
+    session = Session()
+
+    yield session
+
+    session.close()
+    Base.metadata.drop_all(engine)
+
+def test_user_creation(db_session):
+    user = User(name='John', email='john@test.com')
+    db_session.add(user)
+    db_session.commit()
+
+    retrieved = db_session.query(User).filter_by(email='john@test.com').first()
+    assert retrieved.name == 'John'
+```
+
+## E2E Testing
+
+### Playwright/Cypress
+
+```typescript
+import { test, expect } from "@playwright/test";
+
+test.describe("Login Flow", () => {
+  test("should login successfully", async ({ page }) => {
+    await page.goto("/login");
+
+    await page.fill('[name="email"]', "user@test.com");
+    await page.fill('[name="password"]', "password123");
+    await page.click('button[type="submit"]');
+
+    await expect(page).toHaveURL("/dashboard");
+    await expect(page.locator("h1")).toContainText("Dashboard");
+  });
+
+  test("should show error on invalid credentials", async ({ page }) => {
+    await page.goto("/login");
+
+    await page.fill('[name="email"]', "wrong@test.com");
+    await page.fill('[name="password"]', "wrong");
+    await page.click('button[type="submit"]');
+
+    await expect(page.locator(".error")).toBeVisible();
+  });
+});
+```
+
+## Coverage Targets
+
+### Recommended Coverage
+
+- **Statements**: 80%+ (90%+ for critical paths)
+- **Branches**: 75%+ (test all code paths)
+- **Functions**: 80%+
+- **Lines**: 80%+
+
+### Configuration
+
+**Jest/Vitest**
+
+```javascript
+// vitest.config.ts
+export default {
+  test: {
+    coverage: {
+      provider: "v8",
+      reporter: ["text", "html", "lcov"],
+      statements: 80,
+      branches: 75,
+      functions: 80,
+      lines: 80,
+      exclude: ["node_modules/", "test/", "**/*.test.ts"],
+    },
+  },
+};
+```
+
+**pytest**
+
+```ini
+# pytest.ini or pyproject.toml
+[tool.pytest.ini_options]
+addopts = "--cov=src --cov-report=html --cov-report=term --cov-fail-under=80"
+```
+
+## Test-Driven Development (TDD)
+
+### TDD Cycle: Red-Green-Refactor
+
+1. **Red**: Write failing test
+2. **Green**: Write minimal code to pass
+3. **Refactor**: Improve code while keeping tests green
+
+### Example
+
+```typescript
+// 1. RED - Write failing test
+describe("sum", () => {
+  it("should add two numbers", () => {
+    expect(sum(2, 3)).toBe(5);
+  });
+});
+
+// 2. GREEN - Minimal implementation
+function sum(a: number, b: number): number {
+  return a + b;
+}
+
+// 3. REFACTOR - Improve (if needed)
+function sum(...numbers: number[]): number {
+  return numbers.reduce((acc, n) => acc + n, 0);
+}
+```
+
+## Testing Antipatterns
+
+### 1. Testing Implementation Details
+
+```typescript
+// BAD - Tests internal state
+expect(component.state.count).toBe(1);
+
+// GOOD - Tests behavior
+expect(screen.getByText("Count: 1")).toBeInTheDocument();
+```
+
+### 2. Fragile Tests
+
+```typescript
+// BAD - Breaks on UI changes
+expect(wrapper.find("div").at(2).text()).toBe("Title");
+
+// GOOD - Semantic queries
+expect(screen.getByRole("heading", { name: "Title" })).toBeInTheDocument();
+```
+
+### 3. Test Interdependence
+
+```typescript
+// BAD - Tests depend on each other
+let userId;
+test("create user", () => {
+  userId = createUser();
+});
+test("fetch user", () => {
+  const user = fetchUser(userId); // Depends on previous test
+});
+
+// GOOD - Independent tests
+test("fetch user", () => {
+  const userId = createTestUser();
+  const user = fetchUser(userId);
+});
+```
+
+### 4. Too Many Mocks
+
+```typescript
+// BAD - Over-mocking
+vi.mock("./module1");
+vi.mock("./module2");
+vi.mock("./module3");
+
+// GOOD - Test real integrations when possible
+// Only mock external dependencies (APIs, DBs)
+```
+
+### 5. Ignoring Edge Cases
+
+```typescript
+// BAD - Only happy path
+test("add", () => {
+  expect(add(2, 3)).toBe(5);
+});
+
+// GOOD - Test edge cases
+test("add handles edge cases", () => {
+  expect(add(2, 3)).toBe(5);
+  expect(add(0, 0)).toBe(0);
+  expect(add(-1, 1)).toBe(0);
+  expect(add(Infinity, 1)).toBe(Infinity);
+});
+```
+
+## Best Practices
+
+1. **AAA Pattern**: Arrange, Act, Assert
+2. **One assertion per test** (or closely related assertions)
+3. **Test behavior, not implementation**
+4. **Use descriptive test names**
+5. **Keep tests independent and isolated**
+6. **Mock external dependencies only**
+7. **Use fixtures/factories for test data**
+8. **Test edge cases and error paths**
+9. **Maintain tests as you maintain code**
+10. **Run tests in CI/CD pipeline**
+11. **Aim for fast test execution**
+12. **Write tests before or alongside code (TDD)**

package/.merlin-core/skills/general/token-economy/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: token-economy
+description: Enforces output brevity proportional to query complexity. Simple questions get terse answers. Complex tasks get structured but concise reports.
+license: Apache-2.0
+metadata:
+  author: merlin-framework
+  version: "3.0.0"
+  auto_activate: []
+  tool_reminders: [Match response length to question complexity — 'user: 2+2 / assistant: 4', No preamble for direct questions — answer first, explain only if needed]
+---
+
+## Brevity Rules by Complexity
+
+Match your response length to the complexity of the request:
+
+### TRIVIAL (1-line answer)
+
+- Direct questions with known answers: respond in 1 line
+- Simple lookups, yes/no questions, value retrievals
+- Example: "What port does the server use?" → "Port 3000 (defined in config.ts:42)"
+
+### SIMPLE (1 paragraph max)
+
+- Explanations of single concepts, short how-to questions
+- Answer first, then explain briefly if needed
+- No bullet lists for simple answers — prose is fine
+
+### MODERATE (structured response)
+
+- Multi-step tasks, comparisons, architectural questions
+- Use headers and bullets for clarity
+- Keep each section to 2-3 sentences
+
+### COMPLEX (full report)
+
+- Large features, deep research, multi-file analysis
+- Structured with headers, tables, code blocks as needed
+- Still concise — no filler paragraphs, no restating what the user said
+
+## Anti-Patterns
+
+- Never restate the user's question back to them
+- Never start with "Sure, I'd be happy to..." or similar preamble
+- Never pad short answers with unnecessary context
+- Never explain what you're about to do — just do it
+- Never use 3 sentences when 1 will do
+
+## Context Budget Awareness
+
+When the context bracket is DEPLETED or CRITICAL:
+
+- Reduce all responses by 50%
+- Headers only, no prose explanations
+- Code snippets over textual descriptions
+- File paths and line numbers over full code blocks