@venizia/ignis-docs 0.0.8-3 → 0.1.0

package/content/guides/tutorials/testing.md

@@ -0,0 +1,264 @@
+# Testing 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:
+
+| Framework | Description |
+|-----------|-------------|
+| **Jest** | Popular, feature-rich testing framework |
+| **Vitest** | Fast, Vite-native testing framework |
+| **Bun Test** | Built-in test runner for Bun |
+| **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 |
+
+Since IGNIS is just a TypeScript/JavaScript application framework, you can test it with any tool that supports TypeScript.
+
+> [!TIP] IGNIS Testing Extension
+> 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))
+- 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 { testApp, testServer } from './helpers/test-app';
+
+describe('Todo API', () => {
+  beforeAll(async () => {
+    // start() runs the full lifecycle (preConfigure -> registerDataSources ->
+    // registerComponents -> registerControllers) and opens the HTTP server.
+    await testApp.start();
+  });
+
+  afterAll(async () => {
+    await testApp.stop();
+  });
+
+  it('should return list of todos', async () => {
+    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.data)).toBe(true);
+  });
+
+  it('should create a new todo', async () => {
+    const response = await testServer().request('/api/todos', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ title: 'Test Todo' }),
+    });
+
+    expect(response.status).toBe(201);
+    const body = await response.json();
+    expect(body.data.title).toBe('Test Todo');
+  });
+});
+```
+
+### Using Jest
+
+```typescript
+// __tests__/todo.test.ts
+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 testServer().request('/api/todos', { method: 'GET' });
+
+    expect(response.status).toBe(200);
+    const body = await response.json();
+    expect(Array.isArray(body.data)).toBe(true);
+  });
+});
+```
+
+### Using Bun Test
+
+```typescript
+// __tests__/todo.test.ts
+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 testServer().request('/api/todos', { method: 'GET' });
+
+    expect(response.status).toBe(200);
+    const body = await response.json();
+    expect(Array.isArray(body.data)).toBe(true);
+  });
+});
+```
+
+### Using Playwright (E2E)
+
+```typescript
+// e2e/todo.spec.ts
+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`);
+
+    expect(response.ok()).toBeTruthy();
+    const todos = await response.json();
+    expect(Array.isArray(todos.data)).toBe(true);
+  });
+});
+```
+
+## Project Structure
+
+Organize your tests alongside your source code:
+
+```
+my-ignis-app/
+├── src/
+│   ├── controllers/
+│   ├── services/
+│   └── repositories/
+├── __tests__/
+│   ├── controllers/
+│   │   └── todo.controller.test.ts
+│   ├── services/
+│   │   └── todo.service.test.ts
+│   ├── repositories/
+│   │   └── todo.repository.test.ts
+│   └── integration/
+│       └── auth-flow.test.ts
+└── package.json
+```
+
+### Package.json Scripts
+
+Choose scripts based on your preferred test framework:
+
+**Bun Test:**
+```json
+{
+  "scripts": {
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "test:coverage": "bun test --coverage"
+  }
+}
+```
+
+**Vitest:**
+```json
+{
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  }
+}
+```
+
+**Jest:**
+```json
+{
+  "scripts": {
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage"
+  }
+}
+```
+
+**Playwright (E2E):**
+```json
+{
+  "scripts": {
+    "test:e2e": "playwright test",
+    "test:e2e:ui": "playwright test --ui"
+  }
+}
+```
+
+## Best Practices
+
+### 1. Use Descriptive Test Names
+
+```typescript
+test('login with valid credentials returns a JWT and the user id', async () => {
+  // ...
+});
+```
+
+### 2. Isolate Test Data
+
+Give every test its own fixtures - unique ids, fresh records - so tests never depend on execution order.
+
+### 3. Test Edge Cases
+
+Cover the boundaries alongside the happy path: empty input, duplicate ids, missing records, unauthorized callers.
+
+## Next Steps
+
+- [Best Practices](../../best-practices/code-style-standards/) - Code quality standards
+- [Troubleshooting](../../best-practices/troubleshooting-tips.md) - Common issues
+
+## Summary
+
+| What to Test | How |
+|--------------|-----|
+| **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 |
+| **E2E** | Use Playwright or similar for full flow testing |
+
+**Key Takeaways:**
+- Use any test framework you prefer (Jest, Vitest, Bun Test, Playwright, etc.)
+- All frameworks work seamlessly with IGNIS applications

package/content/index.md

@@ -0,0 +1,5 @@
+---
+layout: page
+---
+
+<HomeLanding />

package/content/public/site.webmanifest

@@ -0,0 +1,11 @@
+{
+  "name": "IGNIS",
+  "short_name": "IGNIS",
+  "theme_color": "#AF5F5F",
+  "background_color": "#0B0A0C",
+  "display": "standalone",
+  "icons": [
+    { "src": "/logo.svg", "sizes": "any", "type": "image/svg+xml" },
+    { "src": "/apple-touch-icon.png", "sizes": "180x180", "type": "image/png" }
+  ]
+}

package/{wiki → content}/references/base/application.md

@@ -6,7 +6,7 @@ difficulty: beginner
 
 # Deep Dive: Application
 
-Technical reference for `AbstractApplication` and `BaseApplication` - the foundation classes for every Ignis application.
+Technical reference for `AbstractApplication` and `BaseApplication` - the foundation classes for every IGNIS application.
 
 **Files:**
 - `packages/core/src/base/applications/abstract.ts`
@@ -49,7 +49,7 @@ The constructor:
 
 | Feature | Description |
 | :--- | :--- |
-| **Hono Instance** | Creates and holds two `OpenAPIHono` instances — a main server and a root router |
+| **Hono Instance** | Creates and holds two `OpenAPIHono` instances - a main server and a root router |
 | **Runtime Detection** | Auto-detects Bun or Node.js via `RuntimeModules.detect()` and uses the appropriate server implementation |
 | **Core Bindings** | Registers `CoreBindings.APPLICATION_INSTANCE`, `CoreBindings.APPLICATION_SERVER`, and `CoreBindings.APPLICATION_ROOT_ROUTER` |
 | **Lifecycle Management** | Defines abstract methods (`preConfigure`, `postConfigure`, `setupMiddlewares`, `staticConfigure`, `initialize`, `getAppInfo`) |
@@ -167,7 +167,7 @@ service<Base extends IService, Args extends AnyObject = any>(
   opts?: TMixinOpts<Args>,
 ): Binding<Base>
 
-repository<Base extends IRepository<TTableSchemaWithId>, Args extends AnyObject = any>(
+repository<Base extends IRepository, Args extends AnyObject = any>(
   ctor: TClass<Base>,
   opts?: TMixinOpts<Args>,
 ): Binding<Base>
@@ -305,8 +305,7 @@ interface IApplicationConfigs {
   bootOptions?: IBootOptions;             // Boot system configuration
   debug?: { shouldShowRoutes?: boolean }; // Show registered routes on startup
   transports?: TControllerTransport[];    // Controller transports: 'rest' | 'grpc' (default: ['rest'])
-  strictPath?: boolean;                   // Hono strict path matching (default: true)
-  [key: string]: any;                     // Extensible
+  [key: string]: any;                     // Extensible (e.g. strictPath?: boolean - Hono strict path matching, default: true)
 }
 ```
 

package/{wiki → content}/references/base/bootstrapping.md

@@ -262,10 +262,26 @@ interface IBootstrapper {
 Report generated after boot completion.
 
 ```typescript
-interface IBootReport {}
+interface IBootReport {
+  /** Class names of the booters that actually ran, in execution order. */
+  booters: string[];
+  phases: IBootPhaseReport[];
+  totalDurationMs: number;
+}
+
+interface IBootPhaseReport {
+  phase: TBootPhase;
+  durationMs: number;
+}
 ```
 
-Currently an empty interface, reserved for future enhancements (timing, errors, artifact counts, etc.).
+| Property | Type | Description |
+|----------|------|-------------|
+| `booters` | `string[]` | Class names of the booters that actually ran, in execution order |
+| `phases` | `IBootPhaseReport[]` | Per-phase timing: `{ phase, durationMs }` for each executed phase |
+| `totalDurationMs` | `number` | Total wall-clock duration of the whole `boot()` call |
+
+Built by `Bootstrapper.generateReport()` (private) at the end of `boot()`.
 
 
 ### IApplication
@@ -674,14 +690,12 @@ Load class constructors from files.
 ```typescript
 async function loadClasses(opts: {
   files: string[];
-  root: string;
 }): Promise<AnyType[]>
 ```
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
 | `files` | `string[]` | Array of file paths to load |
-| `root` | `string` | Project root (for error messages) |
 
 **Returns:** `Promise<AnyType[]>` - Array of loaded class constructors (filtered by `isClass` type guard)
 
@@ -693,7 +707,6 @@ const classes = await loadClasses({
     '/path/to/project/controllers/user.controller.js',
     '/path/to/project/controllers/product.controller.js'
   ],
-  root: '/path/to/project'
 });
 // [UserController, ProductController]
 ```