@velajs/testing 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+## 0.2.0 (2026-04-30)
+
+Bugs fixed, rebuilt on `@velajs/vela/internal`, no more `reflect-metadata` dep.
+
+### Fixes
+
+- **Provider override shape was wrong.** `overrideProvider(token).useValue(v)` constructed `{ token, useValue }` but vela's container reads `{ provide, useValue }`. The misleading `as ProviderOptions` cast hid this; nothing actually overrode. Fixed.
+- **`useClass` now uses the container's native `useClass` path** instead of the bogus `useFactory: () => new cls()` workaround. The previous comment claimed `Container.registerOptions` doesn't read `useClass` — it does (`vela/src/container/container.ts`).
+- **`loader.resolveAllInstances()` is now awaited.** Was called synchronously even though vela's signature is async; lifecycle hooks fired before instance resolution finished.
+- **APP_* token wiring uses vela's canonical `bindAppProviders` helper.** Replaces the five duplicated `useGlobalGuards/Pipes/Interceptors/Filters/Middleware(container.resolve(APP_*))` blocks that handled only the single-value case (vela switched to array form months ago). Now stays in lockstep with `VelaFactory.create` automatically.
+
+### Breaking changes
+
+- **`@velajs/vela` peer bumped to `>=1.1.0`.** The `optional: true` flag is removed — the package is unusable without vela.
+- **`reflect-metadata` dependency removed.** Drop `import 'reflect-metadata'` from your test setup files; vela's built-in polyfill is sufficient.
+- **`prepublishOnly` switched from `bun run` to `pnpm run`** to match the rest of the workspace.
+
+### Internal
+
+- **Rebuilt on `@velajs/vela/internal`** for framework primitives (`MetadataRegistry`, `Container`, `RouteManager`, `ModuleLoader`, `ComponentManager`, `VelaApplication`, `bindAppProviders`). Public types still come from `@velajs/vela`.
+- **`bun.lock` deleted** — pnpm is the source of truth.
+
+### Migration
+
+```diff
+- import 'reflect-metadata';
+  import { describe, it, expect } from 'vitest';
+  import { Test } from '@velajs/testing';
+
+- @Module({
+-   providers: [{ token: SomeToken, useValue: 'x' }],
+- })
++ @Module({
++   providers: [{ provide: SomeToken, useValue: 'x' }],
++ })
+  class TestModule {}
+```
+
+(The `token` → `provide` change applies to your `@Module()` providers, not just to overrides — vela's container has always read `provide`. The previous shape silently no-op'd.)
+
+## 0.1.0 (2026-02-20)
+
+Initial release.
+
+- `Test.createTestingModule()` builder.
+- `overrideProvider/Guard/Pipe/Interceptor/Filter` with `useValue/useClass/useFactory`.
+- `TestingModule` with `get()`, `createApplication()`, `close()`.

package/README.md

@@ -0,0 +1,104 @@
+# @velajs/testing
+
+[![npm version](https://img.shields.io/npm/v/@velajs/testing)](https://www.npmjs.com/package/@velajs/testing)
+[![License: MIT](https://img.shields.io/npm/l/@velajs/testing)](https://github.com/velajs/testing/blob/main/LICENSE)
+
+Test-module builder for [Vela](https://github.com/velajs/vela). Compose modules in isolation, override providers/guards/pipes/interceptors/filters, and exercise controllers via Hono's `app.request()` — without bootstrapping the real factory.
+
+## Install
+
+```bash
+pnpm add -D @velajs/testing
+# Peer (already in your project): @velajs/vela ^1.1.0, hono ^4
+```
+
+No `reflect-metadata` needed — Vela ships its own polyfill.
+
+## Quick Start
+
+```ts
+import { describe, it, expect, beforeEach } from 'vitest';
+import { Test } from '@velajs/testing';
+import { MetadataRegistry } from '@velajs/vela';
+import { Injectable, Module } from '@velajs/vela';
+
+@Injectable()
+class CatsService {
+  findAll() { return ['cat1', 'cat2']; }
+}
+
+@Module({ providers: [CatsService] })
+class CatsModule {}
+
+beforeEach(() => MetadataRegistry.clear());
+
+describe('CatsService', () => {
+  it('returns cats', async () => {
+    const moduleRef = await Test.createTestingModule({
+      imports: [CatsModule],
+    }).compile();
+
+    expect(moduleRef.get(CatsService).findAll()).toEqual(['cat1', 'cat2']);
+  });
+});
+```
+
+## Overriding providers
+
+```ts
+const moduleRef = await Test.createTestingModule({ imports: [UsersModule] })
+  .overrideProvider(UsersService)
+  .useValue({ getUsers: () => ['mock-user'] })
+  .compile();
+```
+
+`useValue`, `useClass`, and `useFactory` are all supported. Same builder for `overrideGuard`, `overridePipe`, `overrideInterceptor`, `overrideFilter`.
+
+```ts
+.overrideGuard(AuthGuard).useValue({ canActivate: () => true })
+.overrideInterceptor(LogInterceptor).useClass(NoopInterceptor)
+.overrideProvider(CONFIG).useFactory({
+  factory: (env: EnvService) => ({ env: env.getEnv() }),
+  inject: [EnvService],
+})
+```
+
+Inline providers (skip importing a module):
+
+```ts
+const moduleRef = await Test.createTestingModule({
+  providers: [InlineService],
+}).compile();
+```
+
+## HTTP testing
+
+```ts
+const moduleRef = await Test.createTestingModule({ imports: [ItemsModule] }).compile();
+const app = await moduleRef.createApplication();
+
+const res = await app.getHonoApp().request('/items');
+expect(res.status).toBe(200);
+expect(await res.json()).toEqual([{ id: 1, name: 'Item 1' }]);
+```
+
+## Lifecycle
+
+`compile()` calls `onModuleInit` and `onApplicationBootstrap` automatically. `moduleRef.close()` triggers `onModuleDestroy` and `onApplicationShutdown`.
+
+## API
+
+| Export | Purpose |
+|---|---|
+| `Test.createTestingModule(metadata)` | Returns a `TestingModuleBuilder`. |
+| `TestingModuleBuilder` | Chain `overrideProvider/Guard/Pipe/Interceptor/Filter`, then `.compile()`. |
+| `TestingModule` | Result of `compile()`: `get(token)`, `createApplication()`, `close()`. |
+| `OverrideBy` | The fluent intermediate from `overrideX()` — exposed for type-narrowing. |
+
+## How it's wired
+
+`@velajs/testing` consumes vela's framework primitives via `@velajs/vela/internal` (`MetadataRegistry`, `Container`, `RouteManager`, `ModuleLoader`, `ComponentManager`, `VelaApplication`, `bindAppProviders`). The same `bindAppProviders` that `VelaFactory.create` uses, so test-mode and run-mode app construction stay in lockstep automatically.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { Test } from './test.js';
+export { TestingModule } from './testing-module.js';
+export { TestingModuleBuilder, OverrideBy } from './testing-module.builder.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { Test } from "./test.js";
+export { TestingModule } from "./testing-module.js";
+export { TestingModuleBuilder, OverrideBy } from "./testing-module.builder.js";

package/dist/test.d.ts

@@ -0,0 +1,5 @@
+import type { ModuleOptions } from '@velajs/vela';
+import { TestingModuleBuilder } from './testing-module.builder.js';
+export declare const Test: {
+    createTestingModule(metadata: ModuleOptions): TestingModuleBuilder;
+};

package/dist/test.js

@@ -0,0 +1,6 @@
+import { TestingModuleBuilder } from "./testing-module.builder.js";
+export const Test = {
+    createTestingModule (metadata) {
+        return new TestingModuleBuilder(metadata);
+    }
+};

package/dist/testing-module.builder.d.ts

@@ -0,0 +1,25 @@
+import type { ModuleOptions, Token, Type } from '@velajs/vela';
+import { TestingModule } from './testing-module.js';
+export declare class OverrideBy {
+    private readonly builder;
+    private readonly token;
+    constructor(builder: TestingModuleBuilder, token: Token);
+    useValue(value: unknown): TestingModuleBuilder;
+    useClass(cls: Type): TestingModuleBuilder;
+    useFactory(options: {
+        factory: (...args: unknown[]) => unknown;
+        inject?: Token[];
+    }): TestingModuleBuilder;
+}
+export declare class TestingModuleBuilder {
+    private readonly metadata;
+    private overrides;
+    constructor(metadata: ModuleOptions);
+    overrideProvider(token: Token): OverrideBy;
+    overrideGuard(guard: Type): OverrideBy;
+    overridePipe(pipe: Type): OverrideBy;
+    overrideInterceptor(interceptor: Type): OverrideBy;
+    overrideFilter(filter: Type): OverrideBy;
+    private addOverride;
+    compile(): Promise<TestingModule>;
+}

package/dist/testing-module.builder.js

@@ -0,0 +1,102 @@
+import { ComponentManager, Container, MetadataRegistry, ModuleLoader, RouteManager, VelaApplication, bindAppProviders } from "@velajs/vela/internal";
+import { TestingModule } from "./testing-module.js";
+export class OverrideBy {
+    builder;
+    token;
+    constructor(builder, token){
+        this.builder = builder;
+        this.token = token;
+    }
+    useValue(value) {
+        this.builder['addOverride']({
+            token: this.token,
+            provider: {
+                provide: this.token,
+                useValue: value
+            }
+        });
+        return this.builder;
+    }
+    useClass(cls) {
+        this.builder['addOverride']({
+            token: this.token,
+            provider: {
+                provide: this.token,
+                useClass: cls
+            }
+        });
+        return this.builder;
+    }
+    useFactory(options) {
+        this.builder['addOverride']({
+            token: this.token,
+            provider: {
+                provide: this.token,
+                useFactory: options.factory,
+                inject: options.inject
+            }
+        });
+        return this.builder;
+    }
+}
+export class TestingModuleBuilder {
+    metadata;
+    overrides = [];
+    constructor(metadata){
+        this.metadata = metadata;
+    }
+    overrideProvider(token) {
+        return new OverrideBy(this, token);
+    }
+    overrideGuard(guard) {
+        return new OverrideBy(this, guard);
+    }
+    overridePipe(pipe) {
+        return new OverrideBy(this, pipe);
+    }
+    overrideInterceptor(interceptor) {
+        return new OverrideBy(this, interceptor);
+    }
+    overrideFilter(filter) {
+        return new OverrideBy(this, filter);
+    }
+    addOverride(entry) {
+        const idx = this.overrides.findIndex((o)=>o.token === entry.token);
+        if (idx !== -1) {
+            this.overrides[idx] = entry;
+        } else {
+            this.overrides.push(entry);
+        }
+    }
+    async compile() {
+        let TestRootModule = class TestRootModule {
+        };
+        MetadataRegistry.setModuleOptions(TestRootModule, {
+            imports: this.metadata.imports,
+            providers: this.metadata.providers,
+            controllers: this.metadata.controllers,
+            exports: this.metadata.exports
+        });
+        const container = new Container();
+        container.register({
+            provide: Container,
+            useValue: container
+        });
+        // Register overrides BEFORE module loading so ModuleLoader skips originals.
+        for (const override of this.overrides){
+            container.register(override.provider);
+        }
+        const routeManager = new RouteManager(container);
+        ComponentManager.init(container);
+        const loader = new ModuleLoader(container, routeManager);
+        loader.load(TestRootModule);
+        bindAppProviders(routeManager, container, loader);
+        const app = new VelaApplication(container, routeManager);
+        const instances = await loader.resolveAllInstances();
+        app.setInstances(instances);
+        await app.callOnModuleInit();
+        await app.callOnApplicationBootstrap();
+        await app.initRoutes();
+        return new TestingModule(app, container);
+    }
+}

package/dist/testing-module.d.ts

@@ -0,0 +1,10 @@
+import type { Token, VelaApplication } from '@velajs/vela';
+import type { Container } from '@velajs/vela/internal';
+export declare class TestingModule {
+    private readonly app;
+    private readonly container;
+    constructor(app: VelaApplication, container: Container);
+    get<T>(token: Token<T>): T;
+    createApplication(): Promise<VelaApplication>;
+    close(signal?: string): Promise<void>;
+}

package/dist/testing-module.js

@@ -0,0 +1,18 @@
+export class TestingModule {
+    app;
+    container;
+    constructor(app, container){
+        this.app = app;
+        this.container = container;
+    }
+    get(token) {
+        return this.container.resolve(token);
+    }
+    async createApplication() {
+        await this.app.initRoutes();
+        return this.app;
+    }
+    async close(signal) {
+        await this.app.close(signal);
+    }
+}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@velajs/testing",
+  "version": "0.2.0",
+  "description": "Testing utilities for Vela framework",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && swc src -d dist --strip-leading-paths && tsc --emitDeclarationOnly",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "pnpm run typecheck && pnpm test"
+  },
+  "sideEffects": false,
+  "keywords": [
+    "vela",
+    "testing",
+    "test",
+    "mock",
+    "override",
+    "edge",
+    "framework"
+  ],
+  "author": "ksh",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/velajs/testing.git"
+  },
+  "homepage": "https://github.com/velajs/testing#readme",
+  "bugs": {
+    "url": "https://github.com/velajs/testing/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "peerDependencies": {
+    "@velajs/vela": ">=1.1.0",
+    "hono": ">=4"
+  },
+  "devDependencies": {
+    "@swc/cli": "^0.8.0",
+    "@swc/core": "^1.15.11",
+    "@types/bun": "latest",
+    "@velajs/vela": "^1.1.0",
+    "hono": "^4",
+    "typescript": "^5",
+    "unplugin-swc": "^1.5.9",
+    "vitest": "^4.0.18"
+  },
+  "packageManager": "pnpm@10.20.0",
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "@swc/core",
+      "esbuild"
+    ]
+  }
+}