@vertz/testing 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,739 @@
+# @vertz/testing
+
+Test utilities for Vertz applications. Write fast, isolated tests for your routes, services, and business logic.
+
+## Prerequisites
+
+- **Node.js** 18+ or **Bun** 1.0+
+- **TypeScript** 5.0+
+- **Dependencies:** `@vertz/core`
+- **Test Framework:** Vitest (recommended) or any other test framework
+
+## Installation
+
+```bash
+npm install --save-dev @vertz/testing
+```
+
+This package provides test helpers that work seamlessly with Vitest (recommended) or any other test framework.
+
+## Quick Start
+
+### Testing a Route
+
+```ts
+import { createTestApp } from '@vertz/testing';
+import { UserModule } from './modules/users/user.module';
+import { describe, expect, it } from 'vitest';
+
+describe('User routes', () => {
+  it('returns list of users', async () => {
+    const app = createTestApp().register(UserModule);
+    
+    const res = await app.get('/users');
+    
+    expect(res.ok).toBe(true);
+    expect(res.body).toEqual({
+      users: expect.arrayContaining([
+        expect.objectContaining({ name: expect.any(String) }),
+      ]),
+    });
+  });
+  
+  it('creates a new user', async () => {
+    const app = createTestApp().register(UserModule);
+    
+    const res = await app.post('/users', {
+      body: { name: 'Jane Doe', email: 'jane@example.com' },
+    });
+    
+    expect(res.status).toBe(201);
+    expect(res.body).toMatchObject({
+      id: expect.any(String),
+      name: 'Jane Doe',
+    });
+  });
+});
+```
+
+### Testing a Service
+
+```ts
+import { createTestService } from '@vertz/testing';
+import { UserService, DatabaseService } from './services';
+import { describe, expect, it } from 'vitest';
+
+describe('UserService', () => {
+  it('finds user by ID', async () => {
+    const userService = await createTestService(UserService)
+      .mock(DatabaseService, {
+        query: () => Promise.resolve([{ id: '1', name: 'Jane' }]),
+      });
+    
+    const user = await userService.findById('1');
+    
+    expect(user).toEqual({ id: '1', name: 'Jane' });
+  });
+});
+```
+
+## API Reference
+
+### `createTestApp()`
+
+Creates a test application builder for integration testing routes and modules.
+
+```ts
+import { createTestApp } from '@vertz/testing';
+
+const app = createTestApp();
+```
+
+Returns a `TestApp` instance with the following methods:
+
+#### `app.register(module, options?)`
+
+Register a module with optional configuration.
+
+```ts
+app.register(UserModule);
+app.register(UserModule, { apiKey: 'test-key' });
+```
+
+**Parameters:**
+- `module` — A Vertz module created with `createModule()`
+- `options` — Optional configuration passed to the module
+
+**Returns:** `TestApp` (chainable)
+
+#### `app.mock(service, implementation)`
+
+Mock a service at the application level (applies to all requests).
+
+```ts
+app.mock(DatabaseService, {
+  query: () => Promise.resolve([]),
+});
+```
+
+**Parameters:**
+- `service` — A service definition created with `moduleDef.service()`
+- `implementation` — Partial implementation of the service methods
+
+**Returns:** `TestApp` (chainable)
+
+**Note:** You only need to implement the methods your tests use. Unimplemented methods will throw if called.
+
+#### `app.mockMiddleware(middleware, result)`
+
+Mock a middleware at the application level.
+
+```ts
+app.mockMiddleware(AuthMiddleware, { user: { id: '1' } });
+```
+
+**Parameters:**
+- `middleware` — A middleware definition created with `createMiddleware()`
+- `result` — The value the middleware should provide
+
+**Returns:** `TestApp` (chainable)
+
+#### `app.env(vars)`
+
+Set environment variables for the test application.
+
+```ts
+app.env({ DATABASE_URL: 'test-db', API_KEY: 'test-key' });
+```
+
+**Parameters:**
+- `vars` — Object with environment variable key-value pairs
+
+**Returns:** `TestApp` (chainable)
+
+#### HTTP Methods: `app.get()`, `app.post()`, `app.put()`, `app.patch()`, `app.delete()`, `app.head()`
+
+Make HTTP requests to your application.
+
+```ts
+const res = await app.get('/users');
+const res = await app.post('/users', { body: { name: 'Jane' } });
+const res = await app.put('/users/1', { 
+  body: { name: 'Jane Doe' },
+  headers: { 'Authorization': 'Bearer token' },
+});
+```
+
+**Parameters:**
+- `path` — Request path (e.g., `/users`, `/users/123`)
+- `options` — Optional request options:
+  - `body` — Request body (automatically serialized as JSON)
+  - `headers` — Request headers
+
+**Returns:** `TestRequestBuilder` (awaitable, see below)
+
+### `TestRequestBuilder`
+
+Returned by HTTP method calls. It's **awaitable** and also allows per-request mocking.
+
+#### Await the Request
+
+```ts
+const res = await app.get('/users');
+```
+
+Returns a `TestResponse`:
+
+```ts
+interface TestResponse {
+  status: number;           // HTTP status code
+  body: unknown;            // Parsed response body (JSON)
+  headers: Record<string, string>; // Response headers
+  ok: boolean;              // true if status 2xx
+}
+```
+
+#### Per-Request Mocking
+
+Override mocks for a single request:
+
+```ts
+const res = await app.get('/users')
+  .mock(DatabaseService, {
+    query: () => Promise.resolve([{ id: '1', name: 'Mock User' }]),
+  })
+  .mockMiddleware(AuthMiddleware, { user: { id: 'test-user' } });
+```
+
+**Methods:**
+- `mock(service, implementation)` — Mock a service for this request only
+- `mockMiddleware(middleware, result)` — Mock a middleware for this request only
+
+**Returns:** `TestRequestBuilder` (chainable and awaitable)
+
+### `createTestService(service)`
+
+Creates a test builder for isolated service testing.
+
+```ts
+import { createTestService } from '@vertz/testing';
+
+const serviceInstance = await createTestService(UserService);
+```
+
+**Parameters:**
+- `service` — A service definition created with `moduleDef.service()`
+
+**Returns:** `TestServiceBuilder` (awaitable, see below)
+
+### `TestServiceBuilder`
+
+Returned by `createTestService()`. It's **awaitable** and allows dependency mocking.
+
+#### Await the Service
+
+```ts
+const service = await createTestService(UserService);
+```
+
+Returns the service methods as an object.
+
+#### Mock Dependencies
+
+If the service has injected dependencies, you must mock them:
+
+```ts
+const service = await createTestService(UserService)
+  .mock(DatabaseService, { query: () => Promise.resolve([]) })
+  .mock(CacheService, { get: () => null, set: () => {} });
+```
+
+**Method:**
+- `mock(dependency, implementation)` — Mock an injected dependency
+
+**Returns:** `TestServiceBuilder` (chainable and awaitable)
+
+**Error:** If you await a service with unmocked dependencies, it will throw:
+
+```ts
+// ❌ Throws: "Missing mock for injected dependency 'db'"
+const service = await createTestService(UserService);
+
+// ✅ Correct
+const service = await createTestService(UserService)
+  .mock(DatabaseService, { query: () => [] });
+```
+
+### `DeepPartial<T>`
+
+Type helper for creating partial mocks.
+
+```ts
+import type { DeepPartial } from '@vertz/testing';
+
+const mock: DeepPartial<ComplexService> = {
+  users: {
+    findById: () => Promise.resolve({ id: '1' }),
+    // Other methods optional
+  },
+};
+```
+
+Allows you to implement only the methods you need for your test, even for nested objects.
+
+## Testing Patterns
+
+### Testing with Authentication
+
+Mock the auth middleware to simulate authenticated requests:
+
+```ts
+it('returns user profile when authenticated', async () => {
+  const app = createTestApp()
+    .register(UserModule)
+    .mockMiddleware(AuthMiddleware, { 
+      user: { id: 'user-123', role: 'admin' } 
+    });
+  
+  const res = await app.get('/users/me');
+  
+  expect(res.ok).toBe(true);
+  expect(res.body).toMatchObject({ id: 'user-123' });
+});
+```
+
+Per-request authentication:
+
+```ts
+it('requires authentication', async () => {
+  const app = createTestApp().register(UserModule);
+  
+  // No auth
+  const unauthorized = await app.get('/users/me');
+  expect(unauthorized.status).toBe(401);
+  
+  // With auth
+  const authorized = await app.get('/users/me')
+    .mockMiddleware(AuthMiddleware, { user: { id: '1' } });
+  expect(authorized.ok).toBe(true);
+});
+```
+
+### Testing with Database
+
+Mock database services to avoid hitting a real database:
+
+```ts
+it('creates a user in the database', async () => {
+  const mockDb = {
+    insert: vi.fn().mockResolvedValue({ id: 'new-id' }),
+    query: vi.fn(),
+  };
+  
+  const app = createTestApp()
+    .register(UserModule)
+    .mock(DatabaseService, mockDb);
+  
+  await app.post('/users', { body: { name: 'Jane' } });
+  
+  expect(mockDb.insert).toHaveBeenCalledWith(
+    expect.objectContaining({ name: 'Jane' })
+  );
+});
+```
+
+### Testing Error Handling
+
+```ts
+it('returns 404 for missing user', async () => {
+  const app = createTestApp()
+    .register(UserModule)
+    .mock(DatabaseService, {
+      findById: () => null,
+    });
+  
+  const res = await app.get('/users/999');
+  
+  expect(res.status).toBe(404);
+  expect(res.body).toMatchObject({
+    error: 'NotFound',
+    message: expect.any(String),
+  });
+});
+
+it('returns 400 for invalid input', async () => {
+  const app = createTestApp().register(UserModule);
+  
+  const res = await app.post('/users', {
+    body: { email: 'not-an-email' }, // Invalid email
+  });
+  
+  expect(res.status).toBe(400);
+});
+```
+
+### Testing Services with Dependencies
+
+```ts
+it('user service finds user by email', async () => {
+  const userService = await createTestService(UserService)
+    .mock(DatabaseService, {
+      query: (sql: string) => {
+        if (sql.includes('email')) {
+          return Promise.resolve([{ id: '1', email: 'jane@example.com' }]);
+        }
+        return Promise.resolve([]);
+      },
+    });
+  
+  const user = await userService.findByEmail('jane@example.com');
+  
+  expect(user).toMatchObject({ id: '1', email: 'jane@example.com' });
+});
+```
+
+### Testing with Query Parameters
+
+```ts
+it('filters users by query params', async () => {
+  const app = createTestApp().register(UserModule);
+  
+  const res = await app.get('/users?role=admin&active=true');
+  
+  expect(res.ok).toBe(true);
+  expect(res.body.users).toEqual(
+    expect.arrayContaining([
+      expect.objectContaining({ role: 'admin', active: true }),
+    ])
+  );
+});
+```
+
+### Testing Response Headers
+
+```ts
+it('sets cache headers', async () => {
+  const app = createTestApp().register(UserModule);
+  
+  const res = await app.get('/users');
+  
+  expect(res.headers['cache-control']).toBe('public, max-age=3600');
+});
+```
+
+### Testing with Request Headers
+
+```ts
+it('accepts custom headers', async () => {
+  const app = createTestApp().register(ApiModule);
+  
+  const res = await app.get('/data', {
+    headers: {
+      'X-API-Key': 'test-key',
+      'Accept-Language': 'en-US',
+    },
+  });
+  
+  expect(res.ok).toBe(true);
+});
+```
+
+### Testing Schema Validation
+
+Vertz automatically validates request/response schemas. Test that validation works:
+
+```ts
+it('validates request body against schema', async () => {
+  const app = createTestApp().register(UserModule);
+  
+  const res = await app.post('/users', {
+    body: { name: '', email: 'invalid' }, // Invalid data
+  });
+  
+  expect(res.status).toBe(400);
+  expect(res.body).toMatchObject({
+    error: 'BadRequest',
+  });
+});
+```
+
+### Testing Route Parameters
+
+```ts
+it('handles route parameters', async () => {
+  const app = createTestApp().register(UserModule);
+  
+  const res = await app.get('/users/user-123');
+  
+  expect(res.ok).toBe(true);
+  expect(res.body.id).toBe('user-123');
+});
+```
+
+### Testing Multiple Modules
+
+```ts
+it('integrates multiple modules', async () => {
+  const app = createTestApp()
+    .register(UserModule)
+    .register(AuthModule)
+    .register(PaymentModule);
+  
+  // Test cross-module behavior
+  const loginRes = await app.post('/auth/login', {
+    body: { email: 'jane@example.com', password: 'secret' },
+  });
+  
+  const token = loginRes.body.token;
+  
+  const profileRes = await app.get('/users/me', {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+  
+  expect(profileRes.ok).toBe(true);
+});
+```
+
+### Testing with Service State
+
+If a service maintains state via `onInit`:
+
+```ts
+it('initializes service with state', async () => {
+  const service = await createTestService(CounterService)
+    .mock(StorageService, {
+      load: () => Promise.resolve({ count: 5 }),
+    });
+  
+  const count = await service.getCount();
+  expect(count).toBe(5);
+  
+  await service.increment();
+  const newCount = await service.getCount();
+  expect(newCount).toBe(6);
+});
+```
+
+### Testing Module Options
+
+Pass module options to configure behavior:
+
+```ts
+it('uses module options', async () => {
+  const app = createTestApp().register(UserModule, {
+    maxUsers: 100,
+    enableCache: false,
+  });
+  
+  const res = await app.get('/users');
+  expect(res.ok).toBe(true);
+});
+```
+
+## Integration with Vitest
+
+This package is designed to work seamlessly with Vitest. Add to your `vitest.config.ts`:
+
+```ts
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+  },
+});
+```
+
+Then write tests using Vitest's API:
+
+```ts
+import { createTestApp } from '@vertz/testing';
+import { describe, expect, it, beforeEach, vi } from 'vitest';
+
+describe('User routes', () => {
+  let app: ReturnType<typeof createTestApp>;
+  
+  beforeEach(() => {
+    app = createTestApp().register(UserModule);
+  });
+  
+  it('returns users', async () => {
+    const res = await app.get('/users');
+    expect(res.ok).toBe(true);
+  });
+});
+```
+
+### Using Vitest Mocks
+
+Combine with `vi.fn()` for advanced mocking:
+
+```ts
+it('calls database with correct params', async () => {
+  const queryFn = vi.fn().mockResolvedValue([]);
+  
+  const app = createTestApp()
+    .register(UserModule)
+    .mock(DatabaseService, { query: queryFn });
+  
+  await app.get('/users?role=admin');
+  
+  expect(queryFn).toHaveBeenCalledWith(
+    expect.stringContaining('role = $1'),
+    ['admin']
+  );
+});
+```
+
+## TypeScript Support
+
+All exports are fully typed with strict type inference:
+
+```ts
+import type {
+  TestApp,
+  TestRequestBuilder,
+  TestResponse,
+  TestServiceBuilder,
+  DeepPartial,
+} from '@vertz/testing';
+```
+
+The test utilities preserve full type safety:
+
+```ts
+// ✅ Type-safe service methods
+const service = await createTestService(UserService);
+const user = await service.findById('1'); // Typed as User
+
+// ✅ Type-safe mocks
+app.mock(DatabaseService, {
+  query: () => [], // Return type inferred
+});
+
+// ❌ TypeScript error: Property 'invalidMethod' does not exist
+app.mock(DatabaseService, {
+  invalidMethod: () => {},
+});
+```
+
+## Tips & Best Practices
+
+### 1. Use Per-Request Mocks for Varying Behavior
+
+When you need different behavior per test case, use per-request mocks:
+
+```ts
+it('handles different user states', async () => {
+  const app = createTestApp().register(UserModule);
+  
+  // Active user
+  const activeRes = await app.get('/users/1')
+    .mock(DatabaseService, { findById: () => ({ id: '1', active: true }) });
+  expect(activeRes.body.active).toBe(true);
+  
+  // Inactive user
+  const inactiveRes = await app.get('/users/1')
+    .mock(DatabaseService, { findById: () => ({ id: '1', active: false }) });
+  expect(inactiveRes.body.active).toBe(false);
+});
+```
+
+### 2. Mock Only What You Need
+
+You don't need to implement every method — only the ones your test uses:
+
+```ts
+// ✅ Minimal mock
+app.mock(DatabaseService, {
+  findById: () => ({ id: '1' }),
+  // Other methods omitted — they won't be called
+});
+```
+
+### 3. Use `beforeEach` for Common Setup
+
+```ts
+describe('User API', () => {
+  let app: ReturnType<typeof createTestApp>;
+  
+  beforeEach(() => {
+    app = createTestApp()
+      .register(UserModule)
+      .mock(DatabaseService, { /* common mocks */ });
+  });
+  
+  it('test 1', async () => { /* ... */ });
+  it('test 2', async () => { /* ... */ });
+});
+```
+
+### 4. Test Real Error Cases
+
+Mock errors to test error handling:
+
+```ts
+it('handles database errors', async () => {
+  const app = createTestApp()
+    .register(UserModule)
+    .mock(DatabaseService, {
+      query: () => { throw new Error('Connection failed'); },
+    });
+  
+  const res = await app.get('/users');
+  
+  expect(res.status).toBe(500);
+});
+```
+
+### 5. Test Response Schemas
+
+If you define response schemas, Vertz validates them automatically:
+
+```ts
+it('response matches schema', async () => {
+  const app = createTestApp().register(UserModule);
+  
+  const res = await app.get('/users/1');
+  
+  // If the handler returns data that doesn't match the schema,
+  // the test will throw a ResponseValidationError
+  expect(res.ok).toBe(true);
+});
+```
+
+## Common Errors
+
+### Missing Mock for Dependency
+
+```
+Error: Missing mock for injected dependency "db".
+Call .mock(dbService, impl) before awaiting.
+```
+
+**Solution:** Mock all injected dependencies:
+
+```ts
+const service = await createTestService(UserService)
+  .mock(DatabaseService, { query: () => [] });
+```
+
+### Response Validation Error
+
+```
+ResponseValidationError: Response validation failed: Invalid type
+```
+
+**Cause:** The route handler returned data that doesn't match the response schema.
+
+**Solution:** Fix the handler or the schema to match expected output.
+
+## Related Packages
+
+- [@vertz/core](../core) — Core framework and module system
+- [@vertz/schema](../schema) — Schema validation (used in request/response validation)
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -1,26 +1,45 @@
-import { NamedMiddlewareDef, NamedModule, NamedServiceDef } from "@vertz/core";
+import { NamedMiddlewareDef, NamedModule, NamedServiceDef } from "@vertz/server";
 type DeepPartial<T> = { [P in keyof T]? : T[P] extends object ? DeepPartial<T[P]> : T[P] };
-interface TestResponse {
-	status: number;
+/**
+* Route map entry shape that each route in AppRouteMap must follow.
+*/
+interface RouteMapEntry {
+	params: Record<string, string>;
+	query: Record<string, string>;
 	body: unknown;
 	headers: Record<string, string>;
+	response: unknown;
+}
+/**
+* TestResponse with typed body based on route's response type.
+*/
+interface TestResponse<TResponse = unknown> {
+	status: number;
+	body: TResponse;
+	headers: Record<string, string>;
 	ok: boolean;
 }
-interface TestRequestBuilder extends PromiseLike<TestResponse> {
+interface TestRequestBuilder<TResponse = unknown> extends PromiseLike<TestResponse<TResponse>> {
 	mock<
 		TDeps,
 		TState,
 		TMethods
-	>(service: NamedServiceDef<TDeps, TState, TMethods>, impl: DeepPartial<TMethods>): TestRequestBuilder;
+	>(service: NamedServiceDef<TDeps, TState, TMethods>, impl: DeepPartial<TMethods>): TestRequestBuilder<TResponse>;
 	mockMiddleware<
 		TReq extends Record<string, unknown>,
 		TProv extends Record<string, unknown>
-	>(middleware: NamedMiddlewareDef<TReq, TProv>, result: TProv): TestRequestBuilder;
+	>(middleware: NamedMiddlewareDef<TReq, TProv>, result: TProv): TestRequestBuilder<TResponse>;
 }
-interface RequestOptions {
-	body?: unknown;
+/**
+* Input options for a request, with typed body from the route map.
+*/
+interface RequestOptions<TBody = unknown> {
+	body?: TBody;
 	headers?: Record<string, string>;
 }
+/**
+* Untyped test app interface for backwards compatibility.
+*/
 interface TestApp {
 	register(module: NamedModule, options?: Record<string, unknown>): TestApp;
 	mock<
@@ -40,18 +59,86 @@ interface TestApp {
 	delete(path: string, options?: RequestOptions): TestRequestBuilder;
 	head(path: string, options?: RequestOptions): TestRequestBuilder;
 }
+/**
+* Typed test app interface with route map for type-safe requests.
+* @template TRouteMap - Route map interface mapping route keys (e.g., 'GET /users') to their types.
+*/
+interface TestAppWithRoutes<TRouteMap extends RouteMapEntry> {
+	register(module: NamedModule, options?: Record<string, unknown>): TestAppWithRoutes<TRouteMap>;
+	mock<
+		TDeps,
+		TState,
+		TMethods
+	>(service: NamedServiceDef<TDeps, TState, TMethods>, impl: DeepPartial<TMethods>): TestAppWithRoutes<TRouteMap>;
+	mockMiddleware<
+		TReq extends Record<string, unknown>,
+		TProv extends Record<string, unknown>
+	>(middleware: NamedMiddlewareDef<TReq, TProv>, result: TProv): TestAppWithRoutes<TRouteMap>;
+	env(vars: Record<string, unknown>): TestAppWithRoutes<TRouteMap>;
+	get<TKey extends `GET ${string}` & keyof TRouteMap>(path: string, options?: RequestOptions<TRouteMap[TKey] extends {
+		body: infer TBody;
+	} ? TBody : never>): TestRequestBuilder<TRouteMap[TKey] extends {
+		response: infer TResponse;
+	} ? TResponse : unknown>;
+	post<TKey extends `POST ${string}` & keyof TRouteMap>(path: string, options?: RequestOptions<TRouteMap[TKey] extends {
+		body: infer TBody;
+	} ? TBody : never>): TestRequestBuilder<TRouteMap[TKey] extends {
+		response: infer TResponse;
+	} ? TResponse : unknown>;
+	put<TKey extends `PUT ${string}` & keyof TRouteMap>(path: string, options?: RequestOptions<TRouteMap[TKey] extends {
+		body: infer TBody;
+	} ? TBody : never>): TestRequestBuilder<TRouteMap[TKey] extends {
+		response: infer TResponse;
+	} ? TResponse : unknown>;
+	patch<TKey extends `PATCH ${string}` & keyof TRouteMap>(path: string, options?: RequestOptions<TRouteMap[TKey] extends {
+		body: infer TBody;
+	} ? TBody : never>): TestRequestBuilder<TRouteMap[TKey] extends {
+		response: infer TResponse;
+	} ? TResponse : unknown>;
+	delete<TKey extends `DELETE ${string}` & keyof TRouteMap>(path: string, options?: RequestOptions<TRouteMap[TKey] extends {
+		body: infer TBody;
+	} ? TBody : never>): TestRequestBuilder<TRouteMap[TKey] extends {
+		response: infer TResponse;
+	} ? TResponse : unknown>;
+	head<TKey extends `HEAD ${string}` & keyof TRouteMap>(path: string, options?: RequestOptions<TRouteMap[TKey] extends {
+		body: infer TBody;
+	} ? TBody : never>): TestRequestBuilder<TRouteMap[TKey] extends {
+		response: infer TResponse;
+	} ? TResponse : unknown>;
+}
+/**
+* Creates a test app for making HTTP requests against registered modules.
+* Returns an untyped app for backwards compatibility.
+* @returns A test app instance for registering modules and making requests.
+*/
 declare function createTestApp(): TestApp;
+/**
+* Creates a typed test app with route map for type-safe requests.
+* @template TRouteMap - Route map interface mapping route keys to their types.
+* @returns A typed test app instance.
+*/
+declare function createTestApp<TRouteMap extends RouteMapEntry>(): TestAppWithRoutes<TRouteMap>;
 import { NamedServiceDef as NamedServiceDef2 } from "@vertz/core";
-interface TestServiceBuilder<TMethods> extends PromiseLike<TMethods> {
+interface TestServiceBuilder<
+	TDeps,
+	TState,
+	TMethods,
+	TOptions extends Record<string, unknown> = Record<string, unknown>,
+	TEnv extends Record<string, unknown> = Record<string, unknown>
+> extends PromiseLike<TMethods> {
 	mock<
 		TDep,
-		TState,
+		TDepState,
 		TMock
-	>(service: NamedServiceDef2<TDep, TState, TMock>, impl: DeepPartial<TMock>): TestServiceBuilder<TMethods>;
+	>(service: NamedServiceDef2<TDep, TDepState, TMock>, impl: DeepPartial<TMock>): TestServiceBuilder<TDeps, TState, TMethods, TOptions, TEnv>;
+	options(opts: Partial<TOptions>): TestServiceBuilder<TDeps, TState, TMethods, TOptions, TEnv>;
+	env(env: Partial<TEnv>): TestServiceBuilder<TDeps, TState, TMethods, TOptions, TEnv>;
 }
 declare function createTestService<
 	TDeps,
 	TState,
-	TMethods
->(serviceDef: NamedServiceDef2<TDeps, TState, TMethods>): TestServiceBuilder<TMethods>;
-export { createTestService, createTestApp, TestServiceBuilder, TestResponse, TestRequestBuilder, TestApp, DeepPartial };
+	TMethods,
+	TOptions extends Record<string, unknown> = Record<string, unknown>,
+	TEnv extends Record<string, unknown> = Record<string, unknown>
+>(serviceDef: NamedServiceDef2<TDeps, TState, TMethods, TOptions, TEnv>): TestServiceBuilder<TDeps, TState, TMethods, TOptions, TEnv>;
+export { createTestService, createTestApp, TestServiceBuilder, TestResponse, TestRequestBuilder, TestApp, RouteMapEntry, RequestOptions, DeepPartial };

package/dist/index.js

@@ -1,7 +1,4 @@
 // src/test-app.ts
-import {
-  BadRequestException
-} from "@vertz/core";
 import {
   buildCtx,
   createErrorResponse,
@@ -11,13 +8,9 @@ import {
   runMiddlewareChain,
   Trie
 } from "@vertz/core/internals";
-
-class ResponseValidationError extends Error {
-  constructor(message) {
-    super(`Response validation failed: ${message}`);
-    this.name = "ResponseValidationError";
-  }
-}
+import {
+  BadRequestException
+} from "@vertz/server";
 function validateSchema(schema, value, label) {
   try {
     return schema.parse(value);
@@ -37,10 +30,20 @@ function createTestApp() {
   function buildHandler(perRequest) {
     const trie = new Trie;
     const realServices = new Map;
-    for (const { module } of registrations) {
+    for (const { module, options } of registrations) {
       for (const service of module.services) {
         if (!realServices.has(service)) {
-          realServices.set(service, service.methods({}, undefined));
+          let parsedOptions = {};
+          if (service.options && options) {
+            const parsed = service.options.safeParse(options);
+            if (parsed.success) {
+              parsedOptions = parsed.data;
+            } else {
+              throw new Error(`Invalid options for service ${service.moduleName}: ${parsed.error.issues.map((i) => i.message).join(", ")}`);
+            }
+          }
+          const env = {};
+          realServices.set(service, service.methods({}, undefined, parsedOptions, env));
         }
       }
     }
@@ -197,9 +200,18 @@ function createTestApp() {
   };
   return app;
 }
+
+class ResponseValidationError extends Error {
+  constructor(message) {
+    super(`Response validation failed: ${message}`);
+    this.name = "ResponseValidationError";
+  }
+}
 // src/test-service.ts
 function createTestService(serviceDef) {
   const serviceMocks = new Map;
+  let providedOptions = {};
+  let providedEnv = {};
   async function resolve() {
     const deps = {};
     if (serviceDef.inject) {
@@ -211,14 +223,40 @@ function createTestService(serviceDef) {
         deps[name] = mock;
       }
     }
-    const state = serviceDef.onInit ? await serviceDef.onInit(deps) : undefined;
-    return serviceDef.methods(deps, state);
+    let options = {};
+    if (serviceDef.options) {
+      const parsed = serviceDef.options.safeParse(providedOptions);
+      if (parsed.success) {
+        options = parsed.data;
+      } else {
+        throw new Error(`Invalid options: ${parsed.error.issues.map((i) => i.message).join(", ")}`);
+      }
+    }
+    let env = {};
+    if (serviceDef.env) {
+      const parsed = serviceDef.env.safeParse(providedEnv);
+      if (parsed.success) {
+        env = parsed.data;
+      } else {
+        throw new Error(`Invalid env: ${parsed.error.issues.map((i) => i.message).join(", ")}`);
+      }
+    }
+    const state = serviceDef.onInit ? await serviceDef.onInit(deps, options, env) : undefined;
+    return serviceDef.methods(deps, state, options, env);
   }
   const builder = {
     mock(service, impl) {
       serviceMocks.set(service, impl);
       return builder;
     },
+    options(opts) {
+      providedOptions = opts;
+      return builder;
+    },
+    env(envVars) {
+      providedEnv = envVars;
+      return builder;
+    },
     then(onfulfilled, onrejected) {
       return resolve().then(onfulfilled, onrejected);
     }

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@vertz/testing",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "license": "MIT",
+  "description": "Testing utilities for Vertz applications",
   "repository": {
     "type": "git",
     "url": "https://github.com/vertz-dev/vertz.git",
@@ -30,14 +31,16 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@vertz/core": "workspace:*"
+    "@vertz/core": "workspace:*",
+    "@vertz/server": "workspace:*"
   },
   "devDependencies": {
     "@types/node": "^25.2.1",
     "@vertz/schema": "workspace:*",
+    "@vitest/coverage-v8": "^4.0.18",
     "bunup": "latest",
     "typescript": "^5.7.0",
-    "vitest": "^3.0.0"
+    "vitest": "^4.0.18"
   },
   "engines": {
     "node": ">=22"