@hazejs/testing 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-present hazejs contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,26 @@
-# Temporary Holding Version
+# @hazejs/testing
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Vitest integration for hazejs: test app, HTTP client, `actingAs()` and database helpers.
+
+## Install
+
+```bash
+pnpm add -D @hazejs/testing
+```
+
+## Usage
+
+```ts
+const t = useTestApp()
+
+it('lists posts', async () => {
+  const res = await (await t.actingAs(user)).get('/api/posts')
+  expect(res.status).toBe(200)
+})
+```
+
+Part of [hazejs](https://github.com/penna-org/haze) — see the main README for documentation.
+
+## License
+
+[MIT](./LICENSE)

package/dist/config.d.mts

@@ -0,0 +1,11 @@
+import { HazePluginOptions } from "@hazejs/vite";
+import { ViteUserConfig } from "vitest/config";
+export interface HazeTestConfig extends ViteUserConfig {
+  /** 传给 haze() 插件的选项，例如全栈项目的 `{ srcDir: 'server' }`（默认读取 haze.config.ts） */
+  haze?: Omit<HazePluginOptions, 'standalone'>;
+}
+/**
+ * 后端测试的 Vitest 配置：注册 haze 插件（提供 `virtual:haze/app` 与 `~` 别名），
+ * 并让 Vite 处理 `@hazejs/testing`，使其能导入虚拟模块。
+ */
+export declare function defineHazeTestConfig(config?: HazeTestConfig): ViteUserConfig;

package/dist/config.mjs

@@ -0,0 +1,21 @@
+import { haze } from "@hazejs/vite";
+import { mergeConfig } from "vitest/config";
+// src/config.ts
+/**
+* 后端测试的 Vitest 配置：注册 haze 插件（提供 `virtual:haze/app` 与 `~` 别名），
+* 并让 Vite 处理 `@hazejs/testing`，使其能导入虚拟模块。
+*/
+function defineHazeTestConfig(config = {}) {
+	const { haze: pluginOptions, ...rest } = config;
+	return mergeConfig({
+		plugins: [haze({
+			...pluginOptions,
+			standalone: true
+		})],
+		test: {
+			environment: "node",
+			server: { deps: { inline: ["@hazejs/testing"] } }
+		}
+	}, rest);
+}
+export { defineHazeTestConfig };

package/dist/index.d.mts

@@ -0,0 +1,53 @@
+import { Application, ApplicationOptions, Container, InjectionKey } from "@hazejs/core";
+export interface TestAppOptions extends ApplicationOptions {
+  /** 替换绑定（在提供者 register 之后、boot 之前执行），例如 `c => c.instance(Repo, fakeRepo)` */
+  override?: (container: Container, app: Application) => void | Promise<void>;
+}
+export interface TestRequestInit extends Omit<RequestInit, 'body'> {
+  query?: Record<string, string | number | boolean>;
+}
+export interface TestResponse<T = any> {
+  status: number;
+  ok: boolean;
+  headers: Headers;
+  /** 按 content-type 解析：JSON 为对象，其余为文本 */
+  body: T;
+  text: string;
+}
+export interface TestClient {
+  get: <T = any>(path: string, init?: TestRequestInit) => Promise<TestResponse<T>>;
+  delete: <T = any>(path: string, init?: TestRequestInit) => Promise<TestResponse<T>>;
+  post: <T = any>(path: string, body?: unknown, init?: TestRequestInit) => Promise<TestResponse<T>>;
+  put: <T = any>(path: string, body?: unknown, init?: TestRequestInit) => Promise<TestResponse<T>>;
+  patch: <T = any>(path: string, body?: unknown, init?: TestRequestInit) => Promise<TestResponse<T>>;
+  /** 返回带默认请求头的新客户端，例如 `withHeaders({ authorization: 'Bearer x' })` */
+  withHeaders: (headers: Record<string, string>) => TestClient;
+  /**
+   * 以指定用户登录的客户端：JWT Guard 签发真实令牌（Authorization 头），
+   * Session Guard 生成真实的会话 Cookie。默认使用 config/auth.ts 的默认 Guard。
+   */
+  actingAs: (user: unknown, guard?: string) => Promise<TestClient>;
+}
+export interface TestApp extends TestClient {
+  readonly app: Application;
+  /** 原始 fetch 风格请求 */
+  request: (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+  make: <T>(key: InjectionKey<T>) => T;
+  close: () => Promise<void>;
+}
+/**
+ * 创建测试用应用（不监听端口）。使用 `virtual:haze/app`，与 dev / build 发现同一套
+ * config / route / provider；默认 mode 为 `test`，会加载 `.env.test`。
+ */
+export declare function createTestApp(options?: TestAppOptions): Promise<TestApp>;
+/**
+ * 每个用例前创建全新的应用、用例后释放，返回的对象在用例内直接使用：
+ *
+ * ```ts
+ * const t = useTestApp({ override: c => c.instance(UserRepository, new FakeRepo()) })
+ * it('lists users', async () => {
+ *   expect((await t.get('/api/users')).status).toBe(200)
+ * })
+ * ```
+ */
+export declare function useTestApp(options?: TestAppOptions): TestApp;

package/dist/index.mjs

@@ -0,0 +1,110 @@
+import { issueTestCredentials } from "@hazejs/core";
+import { createApp } from "virtual:haze/app";
+import { afterEach, beforeEach } from "vitest";
+// src/index.ts
+/**
+* 创建测试用应用（不监听端口）。使用 `virtual:haze/app`，与 dev / build 发现同一套
+* config / route / provider；默认 mode 为 `test`，会加载 `.env.test`。
+*/
+async function createTestApp(options = {}) {
+	const { override, setup, ...rest } = options;
+	const app = await createApp({
+		mode: "test",
+		...rest,
+		async setup(app) {
+			await setup?.(app);
+			await override?.(app.container, app);
+		}
+	});
+	return {
+		app,
+		request: (input, init) => app.request(input, init),
+		make: (key) => app.make(key),
+		close: () => app.dispose(),
+		...createClient(app, {})
+	};
+}
+/**
+* 每个用例前创建全新的应用、用例后释放，返回的对象在用例内直接使用：
+*
+* ```ts
+* const t = useTestApp({ override: c => c.instance(UserRepository, new FakeRepo()) })
+* it('lists users', async () => {
+*   expect((await t.get('/api/users')).status).toBe(200)
+* })
+* ```
+*/
+function useTestApp(options = {}) {
+	let current;
+	beforeEach(async () => {
+		current = await createTestApp(options);
+	});
+	afterEach(async () => {
+		await current?.close();
+		current = void 0;
+	});
+	const active = () => {
+		if (!current) throw new Error("useTestApp(): the app is only available inside tests (it/test or hooks after beforeEach)");
+		return current;
+	};
+	return {
+		get app() {
+			return active().app;
+		},
+		request: (input, init) => active().request(input, init),
+		make: (key) => active().make(key),
+		close: () => active().close(),
+		get: (path, init) => active().get(path, init),
+		delete: (path, init) => active().delete(path, init),
+		post: (path, body, init) => active().post(path, body, init),
+		put: (path, body, init) => active().put(path, body, init),
+		patch: (path, body, init) => active().patch(path, body, init),
+		withHeaders: (headers) => active().withHeaders(headers),
+		actingAs: (user, guard) => active().actingAs(user, guard)
+	};
+}
+function createClient(app, defaults) {
+	const send = async (method, path, body, init = {}) => {
+		const { query, headers, ...rest } = init;
+		const url = query ? `${path}${path.includes("?") ? "&" : "?"}${new URLSearchParams(Object.entries(query).map(([k, v]) => [k, String(v)]))}` : path;
+		const merged = new Headers({ ...defaults });
+		new Headers(headers).forEach((value, key) => merged.set(key, value));
+		let payload;
+		if (body !== void 0) {
+			const raw = typeof body === "string" || body instanceof FormData || body instanceof URLSearchParams || body instanceof Blob;
+			payload = raw ? body : JSON.stringify(body);
+			if (!raw && !merged.has("content-type")) merged.set("content-type", "application/json");
+		}
+		const res = await app.request(url, {
+			...rest,
+			method,
+			headers: merged,
+			body: payload
+		});
+		const text = await res.text();
+		const isJson = res.headers.get("content-type")?.includes("json") && text;
+		return {
+			status: res.status,
+			ok: res.ok,
+			headers: res.headers,
+			body: isJson ? JSON.parse(text) : text,
+			text
+		};
+	};
+	return {
+		get: (path, init) => send("GET", path, void 0, init),
+		delete: (path, init) => send("DELETE", path, void 0, init),
+		post: (path, body, init) => send("POST", path, body, init),
+		put: (path, body, init) => send("PUT", path, body, init),
+		patch: (path, body, init) => send("PATCH", path, body, init),
+		withHeaders: (headers) => createClient(app, {
+			...defaults,
+			...headers
+		}),
+		actingAs: async (user, guard) => createClient(app, {
+			...defaults,
+			...await issueTestCredentials(app, user, guard)
+		})
+	};
+}
+export { createTestApp, useTestApp };

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "@hazejs/testing",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "type": "module",
+  "version": "0.1.1",
+  "description": "Vitest helpers for hazejs: test app, HTTP client, actingAs and fakes",
+  "license": "MIT",
+  "homepage": "https://github.com/penna-org/haze/tree/main/packages/testing#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/penna-org/haze.git",
+    "directory": "packages/testing"
+  },
+  "bugs": {
+    "url": "https://github.com/penna-org/haze/issues"
+  },
+  "keywords": [
+    "hazejs",
+    "haze",
+    "nodejs",
+    "typescript",
+    "testing",
+    "vitest"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./config": {
+      "types": "./dist/config.d.mts",
+      "default": "./dist/config.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "peerDependencies": {
+    "vitest": "^5.0.0",
+    "@hazejs/core": "^0.1.1",
+    "@hazejs/vite": "^0.1.1"
+  },
+  "devDependencies": {
+    "vitest": "^5.0.5",
+    "@hazejs/core": "0.1.1",
+    "@hazejs/vite": "0.1.1"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch"
+  }
 }