@venizia/ignis-docs 0.0.8 → 0.2.0

package/content/guides/tutorials/testing.md

@@ -1,12 +1,12 @@
-# Testing Your Ignis Application
+# Testing Your IGNIS Application
 
-This guide shows you how to write tests for your Ignis application.
+This guide shows you how to write tests for your IGNIS application.
 
 **Time to Complete:** ~30 minutes
 
 ## Choose Your Test Framework
 
-**Ignis works with any test framework.** You can use whichever testing tool you prefer:
+**IGNIS works with any test framework.** You can use whichever testing tool you prefer:
 
 | Framework | Description |
 |-----------|-------------|
@@ -16,47 +16,67 @@ This guide shows you how to write tests for your Ignis application.
 | **Playwright** | End-to-end testing for web applications |
 | **node:test** | Node.js native test module |
 | **Mocha** | Flexible testing framework |
-| **Any other** | All test frameworks work with Ignis |
+| **Any other** | All test frameworks work with IGNIS |
 
-Since Ignis is just a TypeScript/JavaScript application framework, you can test it with any tool that supports TypeScript.
+Since IGNIS is just a TypeScript/JavaScript application framework, you can test it with any tool that supports TypeScript.
 
 > [!TIP] IGNIS Testing Extension
-> IGNIS provides its own testing utilities built on `node:test`. These utilities (`TestPlan`, `TestCase`, `TestCaseHandler`) offer a structured approach for organizing tests with lifecycle hooks and shared context. This is optional — use it if you prefer this pattern, or use your favorite test framework directly.
+> IGNIS does not ship its own test framework - use the runner your project already standardizes on (the framework itself is tested with Bun Test).
 
 ## Prerequisites
 
 Before starting, ensure you have:
-- A working Ignis application (see [Building a CRUD API](./building-a-crud-api.md))
+- A working IGNIS application (see [Building a CRUD API](./building-a-crud-api.md))
 - Basic understanding of [Controllers](../core-concepts/rest-controllers.md) and [Repositories](../core-concepts/persistent/)
 
 ## Quick Examples with Popular Frameworks
 
+### Shared Test App Helper
+
+`BaseApplication` has no `request()` method of its own, and `getServer()` has no routes mounted on it until `start()` runs `server.route(basePath, rootRouter)`. The router that actually carries your bound controllers is `getRootRouter()` (an `OpenAPIHono` instance, which has Hono's in-process `request()` testing helper). Start the real application once and reuse it across test files:
+
+```typescript
+// __tests__/helpers/test-app.ts
+import { Application, appConfigs } from '../../src/application';
+
+export const testApp = new Application({ scope: 'TestApp', config: appConfigs });
+
+// getRootRouter() carries the bound controllers - request() exercises them in-process,
+// with no network socket involved.
+export const testServer = () => testApp.getRootRouter();
+```
+
 ### Using Vitest
 
 ```typescript
 // __tests__/todo.test.ts
 import { describe, it, expect, beforeAll, afterAll } from 'vitest';
-import { app } from '../src/application';
+import { testApp, testServer } from './helpers/test-app';
 
 describe('Todo API', () => {
   beforeAll(async () => {
-    // Setup: start server, seed database, etc.
+    // start() runs the full lifecycle (preConfigure -> registerDataSources ->
+    // registerComponents -> registerControllers) and opens the HTTP server.
+    await testApp.start();
   });
 
   afterAll(async () => {
-    // Cleanup: close connections
+    await testApp.stop();
   });
 
   it('should return list of todos', async () => {
-    const response = await app.request('/api/todos', { method: 'GET' });
+    const response = await testServer().request('/api/todos', { method: 'GET' });
 
     expect(response.status).toBe(200);
+    // ControllerFactory's generated GET / wraps reads in { count, data } by default too
+    // (unless the caller sends `x-request-count-data: false`) - unlike the repository API,
+    // where find()/findOne()/findById() return rows directly.
     const body = await response.json();
-    expect(Array.isArray(body)).toBe(true);
+    expect(Array.isArray(body.data)).toBe(true);
   });
 
   it('should create a new todo', async () => {
-    const response = await app.request('/api/todos', {
+    const response = await testServer().request('/api/todos', {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify({ title: 'Test Todo' }),
@@ -64,7 +84,7 @@ describe('Todo API', () => {
 
     expect(response.status).toBe(201);
     const body = await response.json();
-    expect(body.title).toBe('Test Todo');
+    expect(body.data.title).toBe('Test Todo');
   });
 });
 ```
@@ -73,15 +93,23 @@ describe('Todo API', () => {
 
 ```typescript
 // __tests__/todo.test.ts
-import { app } from '../src/application';
+import { testApp, testServer } from './helpers/test-app';
 
 describe('Todo API', () => {
+  beforeAll(async () => {
+    await testApp.start();
+  });
+
+  afterAll(async () => {
+    await testApp.stop();
+  });
+
   it('should return list of todos', async () => {
-    const response = await app.request('/api/todos', { method: 'GET' });
+    const response = await testServer().request('/api/todos', { method: 'GET' });
 
     expect(response.status).toBe(200);
     const body = await response.json();
-    expect(Array.isArray(body)).toBe(true);
+    expect(Array.isArray(body.data)).toBe(true);
   });
 });
 ```
@@ -90,16 +118,24 @@ describe('Todo API', () => {
 
 ```typescript
 // __tests__/todo.test.ts
-import { describe, it, expect } from 'bun:test';
-import { app } from '../src/application';
+import { describe, it, expect, beforeAll, afterAll } from 'bun:test';
+import { testApp, testServer } from './helpers/test-app';
 
 describe('Todo API', () => {
+  beforeAll(async () => {
+    await testApp.start();
+  });
+
+  afterAll(async () => {
+    await testApp.stop();
+  });
+
   it('should return list of todos', async () => {
-    const response = await app.request('/api/todos', { method: 'GET' });
+    const response = await testServer().request('/api/todos', { method: 'GET' });
 
     expect(response.status).toBe(200);
     const body = await response.json();
-    expect(Array.isArray(body)).toBe(true);
+    expect(Array.isArray(body.data)).toBe(true);
   });
 });
 ```
@@ -112,459 +148,15 @@ import { test, expect } from '@playwright/test';
 
 test.describe('Todo Application', () => {
   test('should display todo list', async ({ request }) => {
-    const response = await request.get('http://localhost:3000/api/todos');
+    const response = await request.get(`http://localhost:3000/api/todos`);
 
     expect(response.ok()).toBeTruthy();
     const todos = await response.json();
-    expect(Array.isArray(todos)).toBe(true);
+    expect(Array.isArray(todos.data)).toBe(true);
   });
 });
 ```
 
-## Using IGNIS Testing Extension
-
-IGNIS provides its own testing utilities built on `node:test` for a more structured approach.
-
-### 1. Create Your First Test
-
-Create a test file in your project:
-
-```typescript
-// __tests__/hello.test.ts
-import {
-  TestPlan,
-  TestDescribe,
-  TestCase,
-  TestCaseHandler,
-  TestCaseDecisions,
-} from '@venizia/ignis-helpers';
-
-// Step 1: Define a Test Handler
-class HelloHandler extends TestCaseHandler {
-  async execute() {
-    // The action to test
-    const message = 'Hello, Ignis!';
-    return { message };
-  }
-
-  getValidator() {
-    // Validate the result
-    return (result: { message: string }) => {
-      if (result.message === 'Hello, Ignis!') {
-        return TestCaseDecisions.SUCCESS;
-      }
-      return TestCaseDecisions.FAIL;
-    };
-  }
-}
-
-// Step 2: Create a Test Plan
-const helloTestPlan = TestPlan.newInstance({
-  scope: 'Hello World Tests',
-  testCases: [
-    TestCase.withOptions({
-      code: 'HELLO-001',
-      description: 'Should return greeting message',
-      expectation: 'Message equals "Hello, Ignis!"',
-      handler: new HelloHandler({ context: {} as any }),
-    }),
-  ],
-});
-
-// Step 3: Run the Test
-TestDescribe.withTestPlan({ testPlan: helloTestPlan }).run();
-```
-
-### 2. Run Tests
-
-```bash
-# Using Bun
-bun test
-
-# Using Node.js
-node --test __tests__/*.test.ts
-```
-
-## Core Concepts
-
-### Test Framework Components
-
-| Component | Purpose |
-|-----------|---------|
-| **TestPlan** | Organizes a test suite with lifecycle hooks and shared context |
-| **TestCase** | A single test unit with code, description, and handler |
-| **TestCaseHandler** | Encapsulates test execution and validation logic |
-| **TestDescribe** | Runs test plans using `node:test` |
-
-### Test Case Decisions
-
-| Decision | Meaning |
-|----------|---------|
-| `TestCaseDecisions.SUCCESS` | Test passed |
-| `TestCaseDecisions.FAIL` | Test failed |
-| `TestCaseDecisions.UNKNOWN` | Result undetermined |
-
-### Lifecycle Hooks
-
-| Hook | When | Use Case |
-|------|------|----------|
-| `before` | Before all tests | Start server, seed database |
-| `after` | After all tests | Close connections, cleanup |
-| `beforeEach` | Before each test | Reset state |
-| `afterEach` | After each test | Clear test data |
-
-## Testing Controllers
-
-Here's how to test an HTTP controller:
-
-```typescript
-// __tests__/todo.controller.test.ts
-import {
-  TestPlan,
-  TestDescribe,
-  TestCase,
-  TestCaseHandler,
-  TestCaseDecisions,
-} from '@venizia/ignis-helpers';
-import { app } from '../src/application'; // Your Ignis app
-
-// Handler for testing GET /todos
-class GetTodosHandler extends TestCaseHandler {
-  async execute() {
-    // Make HTTP request to your app
-    const response = await app.request('/api/todos', {
-      method: 'GET',
-    });
-
-    return {
-      status: response.status,
-      body: await response.json(),
-    };
-  }
-
-  getValidator() {
-    return (result: { status: number; body: any }) => {
-      // Validate status code
-      if (result.status !== 200) {
-        return TestCaseDecisions.FAIL;
-      }
-
-      // Validate response is an array
-      if (!Array.isArray(result.body)) {
-        return TestCaseDecisions.FAIL;
-      }
-
-      return TestCaseDecisions.SUCCESS;
-    };
-  }
-}
-
-// Handler for testing POST /todos
-class CreateTodoHandler extends TestCaseHandler {
-  async execute() {
-    const response = await app.request('/api/todos', {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({
-        title: 'Test Todo',
-        description: 'Created by test',
-      }),
-    });
-
-    return {
-      status: response.status,
-      body: await response.json(),
-    };
-  }
-
-  getValidator() {
-    return (result: { status: number; body: any }) => {
-      if (result.status !== 201) {
-        return TestCaseDecisions.FAIL;
-      }
-
-      if (result.body.title !== 'Test Todo') {
-        return TestCaseDecisions.FAIL;
-      }
-
-      return TestCaseDecisions.SUCCESS;
-    };
-  }
-}
-
-// Create test plan
-const todoControllerTests = TestPlan.newInstance({
-  scope: 'Todo Controller',
-  hooks: {
-    before: async () => {
-      console.log('Setting up Todo controller tests...');
-      // Start server or setup test database
-    },
-    after: async () => {
-      console.log('Cleaning up...');
-      // Cleanup resources
-    },
-  },
-  testCases: [
-    TestCase.withOptions({
-      code: 'TODO-001',
-      description: 'GET /todos returns list of todos',
-      expectation: 'Status 200 with array response',
-      handler: new GetTodosHandler({ context: {} as any }),
-    }),
-    TestCase.withOptions({
-      code: 'TODO-002',
-      description: 'POST /todos creates a new todo',
-      expectation: 'Status 201 with created todo',
-      handler: new CreateTodoHandler({ context: {} as any }),
-    }),
-  ],
-});
-
-TestDescribe.withTestPlan({ testPlan: todoControllerTests }).run();
-```
-
-## Testing with Shared Context
-
-Use the test plan's context to share data between tests (like authentication tokens):
-
-```typescript
-// __tests__/auth.test.ts
-import {
-  TestPlan,
-  TestDescribe,
-  TestCase,
-  TestCaseHandler,
-  TestCaseDecisions,
-  ITestContext,
-} from '@venizia/ignis-helpers';
-
-// Define context shape
-interface AuthContext {
-  token: string;
-  userId: string;
-}
-
-// Handler that uses shared context
-class SecureEndpointHandler extends TestCaseHandler<AuthContext> {
-  async execute() {
-    // Get token from context (set in before hook)
-    const token = this.context.getSync<string>({ key: 'token' });
-
-    const response = await app.request('/api/profile', {
-      method: 'GET',
-      headers: {
-        Authorization: `Bearer ${token}`,
-      },
-    });
-
-    return {
-      status: response.status,
-      body: await response.json(),
-    };
-  }
-
-  getValidator() {
-    return (result: { status: number; body: any }) => {
-      if (result.status === 200 && result.body.id) {
-        return TestCaseDecisions.SUCCESS;
-      }
-      return TestCaseDecisions.FAIL;
-    };
-  }
-}
-
-const authTests = TestPlan.newInstance<AuthContext>({
-  scope: 'Authentication Tests',
-  hooks: {
-    before: async (testPlan: ITestContext<AuthContext>) => {
-      // Login and store token in context
-      const loginResponse = await app.request('/api/auth/login', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({
-          email: 'test@example.com',
-          password: 'password123',
-        }),
-      });
-
-      const { token, userId } = await loginResponse.json();
-
-      // Bind to context for use in test cases
-      testPlan.bind({ key: 'token', value: token });
-      testPlan.bind({ key: 'userId', value: userId });
-    },
-  },
-  testCases: [
-    TestCase.withOptions({
-      code: 'AUTH-001',
-      description: 'Authenticated user can access profile',
-      expectation: 'Returns user profile with status 200',
-      handler: new SecureEndpointHandler({ context: {} as any }),
-    }),
-  ],
-});
-
-TestDescribe.withTestPlan({ testPlan: authTests }).run();
-```
-
-## Testing Repositories
-
-Test your data access layer directly:
-
-```typescript
-// __tests__/todo.repository.test.ts
-import {
-  TestPlan,
-  TestDescribe,
-  TestCase,
-  TestCaseHandler,
-  TestCaseDecisions,
-} from '@venizia/ignis-helpers';
-import { TodoRepository } from '../src/repositories/todo.repository';
-import { Container } from '@venizia/ignis-inversion';
-
-// Setup container for DI
-const container = new Container();
-
-class CreateTodoRepoHandler extends TestCaseHandler {
-  async execute() {
-    const todoRepo = container.get<TodoRepository>('repositories.TodoRepository');
-
-    const created = await todoRepo.create({
-      title: 'Repository Test',
-      description: 'Testing repository layer',
-      isCompleted: false,
-    });
-
-    return { todo: created };
-  }
-
-  getValidator() {
-    return (result: { todo: any }) => {
-      if (result.todo && result.todo.id && result.todo.title === 'Repository Test') {
-        return TestCaseDecisions.SUCCESS;
-      }
-      return TestCaseDecisions.FAIL;
-    };
-  }
-}
-
-class FindTodoRepoHandler extends TestCaseHandler {
-  async execute() {
-    const todoRepo = container.get<TodoRepository>('repositories.TodoRepository');
-
-    const todos = await todoRepo.find({
-      where: { isCompleted: false },
-      limit: 10,
-    });
-
-    return { todos, count: todos.length };
-  }
-
-  getValidator() {
-    return (result: { todos: any[]; count: number }) => {
-      if (Array.isArray(result.todos) && result.count >= 0) {
-        return TestCaseDecisions.SUCCESS;
-      }
-      return TestCaseDecisions.FAIL;
-    };
-  }
-}
-
-const repoTests = TestPlan.newInstance({
-  scope: 'Todo Repository',
-  hooks: {
-    before: async () => {
-      // Setup DI container and database connection
-      container.bind('repositories.TodoRepository').toClass(TodoRepository);
-    },
-    after: async () => {
-      // Cleanup test data
-    },
-  },
-  testCases: [
-    TestCase.withOptions({
-      code: 'REPO-001',
-      description: 'Can create a todo via repository',
-      expectation: 'Returns created todo with ID',
-      handler: new CreateTodoRepoHandler({ context: {} as any }),
-    }),
-    TestCase.withOptions({
-      code: 'REPO-002',
-      description: 'Can find todos with filters',
-      expectation: 'Returns array of matching todos',
-      handler: new FindTodoRepoHandler({ context: {} as any }),
-    }),
-  ],
-});
-
-TestDescribe.withTestPlan({ testPlan: repoTests }).run();
-```
-
-## Testing Services
-
-Test business logic in isolation:
-
-```typescript
-// __tests__/todo.service.test.ts
-import {
-  TestPlan,
-  TestDescribe,
-  TestCase,
-  TestCaseHandler,
-  TestCaseDecisions,
-} from '@venizia/ignis-helpers';
-import { TodoService } from '../src/services/todo.service';
-
-class CompleteTodoHandler extends TestCaseHandler {
-  async execute() {
-    const todoService = new TodoService();
-
-    // Create a todo first
-    const todo = await todoService.create({
-      title: 'Test completion',
-      isCompleted: false,
-    });
-
-    // Mark as complete
-    const completed = await todoService.markAsComplete(todo.id);
-
-    return { original: todo, completed };
-  }
-
-  getValidator() {
-    return (result: { original: any; completed: any }) => {
-      // Original should be incomplete
-      if (result.original.isCompleted !== false) {
-        return TestCaseDecisions.FAIL;
-      }
-
-      // Completed should be complete
-      if (result.completed.isCompleted !== true) {
-        return TestCaseDecisions.FAIL;
-      }
-
-      return TestCaseDecisions.SUCCESS;
-    };
-  }
-}
-
-const serviceTests = TestPlan.newInstance({
-  scope: 'Todo Service',
-  testCases: [
-    TestCase.withOptions({
-      code: 'SVC-001',
-      description: 'Can mark todo as complete',
-      expectation: 'Todo isCompleted changes from false to true',
-      handler: new CompleteTodoHandler({ context: {} as any }),
-    }),
-  ],
-});
-
-TestDescribe.withTestPlan({ testPlan: serviceTests }).run();
-```
-
 ## Project Structure
 
 Organize your tests alongside your source code:
@@ -636,73 +228,24 @@ Choose scripts based on your preferred test framework:
 
 ## Best Practices
 
-### 1. Use Descriptive Test Codes
+### 1. Use Descriptive Test Names
 
 ```typescript
-TestCase.withOptions({
-  code: 'AUTH-LOGIN-001',  // Feature-Action-Number
-  description: 'User can login with valid credentials',
-  expectation: 'Returns JWT token and user ID',
+test('login with valid credentials returns a JWT and the user id', async () => {
   // ...
 });
 ```
 
 ### 2. Isolate Test Data
 
-```typescript
-hooks: {
-  beforeEach: async (testPlan) => {
-    // Create fresh test data for each test
-    const testTodo = await createTestTodo();
-    testPlan.bind({ key: 'testTodoId', value: testTodo.id });
-  },
-  afterEach: async (testPlan) => {
-    // Clean up after each test
-    const todoId = testPlan.getSync({ key: 'testTodoId' });
-    await deleteTestTodo(todoId);
-  },
-}
-```
+Give every test its own fixtures - unique ids, fresh records - so tests never depend on execution order.
 
 ### 3. Test Edge Cases
 
-```typescript
-// Test empty results
-TestCase.withOptions({
-  code: 'TODO-FIND-002',
-  description: 'Returns empty array when no todos match filter',
-  expectation: 'Empty array with status 200',
-  handler: new FindNonExistentHandler({ context: {} as any }),
-});
-
-// Test validation errors
-TestCase.withOptions({
-  code: 'TODO-CREATE-003',
-  description: 'Rejects todo without title',
-  expectation: 'Status 400 with validation error',
-  handler: new CreateInvalidTodoHandler({ context: {} as any }),
-});
-```
-
-### 4. Keep Handlers Focused
-
-Each handler should test one specific behavior:
-
-```typescript
-// Good: Focused on one behavior
-class CreateTodoHandler extends TestCaseHandler {
-  async execute() { /* only create logic */ }
-}
-
-// Avoid: Multiple behaviors in one handler
-class CreateAndUpdateAndDeleteHandler extends TestCaseHandler {
-  async execute() { /* too many things */ }
-}
-```
+Cover the boundaries alongside the happy path: empty input, duplicate ids, missing records, unauthorized callers.
 
 ## Next Steps
 
-- [Testing Reference](../../extensions/helpers/testing/) - Complete API documentation
 - [Best Practices](../../best-practices/code-style-standards/) - Code quality standards
 - [Troubleshooting](../../best-practices/troubleshooting-tips.md) - Common issues
 
@@ -710,7 +253,7 @@ class CreateAndUpdateAndDeleteHandler extends TestCaseHandler {
 
 | What to Test | How |
 |--------------|-----|
-| **Controllers** | Use `app.request()` to make HTTP calls |
+| **Controllers** | Use `getRootRouter().request()` to make in-process HTTP calls |
 | **Services** | Instantiate and call methods directly |
 | **Repositories** | Use DI container, test with real/mock DB |
 | **Integration** | Chain multiple operations with shared context |
@@ -718,5 +261,4 @@ class CreateAndUpdateAndDeleteHandler extends TestCaseHandler {
 
 **Key Takeaways:**
 - Use any test framework you prefer (Jest, Vitest, Bun Test, Playwright, etc.)
-- IGNIS provides optional testing utilities (`TestPlan`, `TestCase`, `TestCaseHandler`) built on `node:test`
-- All frameworks work seamlessly with Ignis applications
+- All frameworks work seamlessly with IGNIS applications