sonamu 0.10.5 → 0.10.7

package/src/skills/sonamu-testing/references/helpers.md

@@ -0,0 +1,185 @@
+# Test Helpers
+
+## Fixture
+
+### createFixtureLoader
+
+```typescript
+// api/src/testing/fixture.ts
+import { createFixtureLoader } from "sonamu/test";
+import { CompanyModel } from "../application/company/company.model";
+import { UserModel } from "../application/user/user.model";
+
+export const loadFixtures = createFixtureLoader({
+  company01: async () => CompanyModel.findById("A", 1),
+  user01: async () => UserModel.findById("A", 1),
+});
+```
+
+### Using in tests
+
+```typescript
+import { loadFixtures } from "../../testing/fixture";
+
+test("update company info", async () => {
+  const f0 = await loadFixtures(["company01"]);
+
+  await CompanyModel.save([
+    {
+      ...f0.company01,
+      name: "Updated Company",
+    },
+  ]);
+
+  const f1 = await loadFixtures(["company01"]);
+  expect(f1.company01.name).toBe("Updated Company");
+});
+```
+
+## Naite (Test Tracing System)
+
+**→ Detailed guide (key list, chaining filters, wildcard, del, internal structure): `sonamu-naite`**
+
+Naite is a tracing system that records values with `Naite.t("key", value)` in source code and validates them with `Naite.get("key")` in tests.
+
+### Commonly Used Patterns in Tests
+
+```typescript
+import { Naite } from "sonamu";
+
+// Query validation
+expect(Naite.get("esq-query").first()).not.contain("limit");
+
+// UpsertBuilder behavior validation
+const trace = Naite.get("puri:ub-upserted").first();
+expect(trace).toMatchObject({ tableName: "users", rowCount: 3 });
+
+// Fetch methods: .first(), .last(), .at(n), .result() (full array)
+// Filters: .fromFile("user.model.ts"), .fromFunction("findById"), .where("data.tableName", "=", "users")
+```
+
+
+## Test Helper: expectQuery
+
+Helper for validating specific parts of SQL queries (see miomock for reference):
+
+```typescript
+// api/src/testing/expect-query.ts
+import { type AST, Parser } from "node-sql-parser";
+import { expect } from "vitest";
+
+export type QueryPart =
+  | "type"
+  | "table"
+  | "columns"
+  | "set"
+  | "where"
+  | "join"
+  | "orderBy"
+  | "pagination"
+  | "groupBy"
+  | "having";
+
+export function expectQuery(query: string, part?: QueryPart) {
+  if (!part) return expect(query);
+  const ast = parseQuery(query);
+  const extractedSql = extractors[part](ast);
+  return expect(extractedSql);
+}
+```
+
+### Usage Examples
+
+```typescript
+import { expectQuery } from "../testing/expect-query";
+
+test("validate select query", async () => {
+  const db = UserModel.getPuri("r");
+  await db.table("users").select({ id: "users.id" });
+  const query = Naite.get("puri:executed-query").first();
+
+  expectQuery(query, "type").toBe("select");
+  expectQuery(query, "table").toBe("users");
+  expectQuery(query, "columns").toMatchInlineSnapshot(`""users"."id" AS \`id\`"`);
+});
+
+test("validate where condition", async () => {
+  const db = UserModel.getPuri("r");
+  await db.table("users").where("users.id", 1);
+  const query = Naite.get("puri:executed-query").first();
+
+  expectQuery(query, "where").toMatchInlineSnapshot(`""users"."id" = 1"`);
+});
+
+test("validate join", async () => {
+  const db = UserModel.getPuri("r");
+  await db.table("employees").leftJoin("departments", "employees.department_id", "departments.id");
+  const query = Naite.get("puri:executed-query").first();
+
+  expectQuery(query, "join").toMatchInlineSnapshot(
+    `"LEFT JOIN departments ON "employees"."department_id" = "departments"."id""`,
+  );
+});
+```
+
+## Test Helper: expectUB
+
+UpsertBuilder state validation helper (see miomock for reference):
+
+```typescript
+// api/src/testing/expect-ub.ts
+import type { UpsertBuilder } from "sonamu";
+import { expect } from "vitest";
+
+export type UBPart =
+  | "tables"
+  | "hasTable"
+  | "rowCount"
+  | "rows"
+  | "row"
+  | "refs"
+  | "uniquesMap"
+  | "uniqueIndexes";
+
+export function expectUB<P extends UBPart>(
+  ub: UpsertBuilder,
+  part: P,
+  tableName?: string,
+  index?: number,
+) {
+  // ... implementation
+}
+```
+
+### Usage Examples
+
+```typescript
+import { expectUB } from "../testing/expect-ub";
+
+test("validate UpsertBuilder state", async () => {
+  const ub = new UpsertBuilder();
+
+  // initial state
+  expectUB(ub, "hasTable", "users").toBe(false);
+  expectUB(ub, "tables").toEqual([]);
+
+  // after register
+  ub.register("users", {
+    email: "test@test.com",
+    username: "test",
+    password: "pw",
+    role: "normal",
+  });
+
+  expectUB(ub, "hasTable", "users").toBe(true);
+  expectUB(ub, "rowCount", "users").toBe(1);
+  expectUB(ub, "row", "users", 0).toMatchObject({
+    email: "test@test.com",
+    username: "test",
+  });
+
+  // confirm reset after upsert
+  await ub.upsert(wdb, "users");
+  expectUB(ub, "rowCount", "users").toBe(0);
+});
+```

package/src/skills/sonamu-testing/references/patterns.md

@@ -0,0 +1,263 @@
+# Test Patterns
+
+## Enum Value Usage Rules
+
+**CRITICAL: Only use enum values defined in entity.json.**
+
+### Rules
+
+1. Check the exact value list for enum fields in entity.json
+2. If possible, use TypeScript enum types from `sonamu.generated.ts` (type-safe)
+3. Set valid enum values as defaults in test-helpers.ts
+4. Do not use arbitrary strings
+
+```typescript
+// WRONG: written based on guesses
+role: "user"; // entity.json defines it as "normal"
+status: "in_progress"; // entity.json defines it as "pending"
+
+// CORRECT: written after checking entity.json
+role: "normal"; // exact value from entity.json
+status: "pending"; // exact value from entity.json
+
+// BEST: use TypeScript enum
+import { UserRoleEnum } from "../sonamu.generated";
+role: UserRoleEnum.normal;
+```
+
+**Core principle: entity.json is the Single Source of Truth.**
+
+
+## Test Basic Patterns
+
+### bootstrap
+
+`bootstrap(vi)` call required in all test files:
+
+```typescript
+import { bootstrap, test } from "sonamu/test";
+import { describe, expect, vi } from "vitest";
+
+bootstrap(vi);
+
+describe("MyTest", () => {
+  test("test case", async () => {
+    // ...
+  });
+});
+```
+
+**bootstrap options:**
+
+```typescript
+// Default: forTesting: true (fast, skips Syncer/Task)
+bootstrap(vi);
+
+// forTesting: false - full initialization (loads Syncer, Task, EntityManager, etc.)
+// Used in tests for migrator, syncer, template, etc.
+bootstrap(vi, { forTesting: false });
+```
+
+### test vs testAs
+
+```typescript
+// Unauthenticated test - Context.user is null
+test("unauthenticated test", async () => {
+  const me = await UserModel.me();
+  expect(me).toBeNull();
+});
+
+// Authenticated test - Context.user is set
+import type { UserSubsetSS } from "../sonamu.generated";
+
+const adminUser: UserSubsetSS = {
+  id: 1,
+  created_at: new Date(),
+  email: "admin@test.com",
+  username: "admin",
+  role: "admin",
+};
+
+testAs(adminUser, "admin permission test", async () => {
+  const me = await UserModel.me();
+  expect(me?.role).toBe("admin");
+});
+```
+
+### test.each
+
+```typescript
+test.each([
+  { input: "user@example.com", expected: true },
+  { input: "invalid-email", expected: false },
+])("email validation: $input → $expected", async ({ input, expected }) => {
+  expect(validateEmail(input)).toBe(expected);
+});
+```
+
+
+## Mock Patterns
+
+### setup-mocks.ts
+
+```typescript
+// api/src/testing/setup-mocks.ts
+import { Naite } from "sonamu";
+import { vi } from "vitest";
+
+vi.mock("fs/promises", async (importOriginal) => {
+  const actual = (await importOriginal()) as typeof import("fs/promises");
+  return {
+    ...actual,
+    access: vi.fn((path, mode) => {
+      // virtual file system check
+      const vfs = Naite.get("mock:fs/promises:virtualFileSystem").result();
+      if (vfs.some((v) => v === path)) {
+        return Promise.resolve();
+      }
+      return actual.access(path, mode);
+    }),
+    writeFile: vi.fn((path, data) => {
+      Naite.t("fs/promises:writeFile", { path, data });
+    }),
+    rm: vi.fn(async (path, options) => {
+      Naite.t("fs/promises:rm", { path, options });
+      return Promise.resolve();
+    }),
+  };
+});
+```
+
+### test-helpers.ts
+
+```typescript
+// api/src/testing/test-helpers.ts
+import { Entity, EntityManager, type EntityJson } from "sonamu";
+import { vi } from "vitest";
+
+// Mocking EntityManager.get
+export function mockEntityManagerGet(
+  targetEntityId: string,
+  overrideCallback: (original: EntityJson) => EntityJson,
+) {
+  const originalEntityJson = EntityManager.get(targetEntityId).toJson();
+  const originalGet = EntityManager.get;
+  return vi.spyOn(EntityManager, "get").mockImplementation((entityId) => {
+    if (entityId === targetEntityId) {
+      return new Entity(overrideCallback(originalEntityJson));
+    }
+    return originalGet.call(EntityManager, entityId);
+  });
+}
+```
+
+## CRUD Test Patterns
+
+### Create & Read
+
+```typescript
+test("Create - create new user", async () => {
+  const [userId] = await UserModel.save([
+    {
+      email: "newuser@test.com",
+      username: "newuser",
+      password: "hashedpassword",
+      role: "normal",
+    },
+  ]);
+
+  expect(userId).toBeGreaterThan(0);
+
+  const user = await UserModel.findById("A", userId);
+  expect(user.email).toBe("newuser@test.com");
+});
+```
+
+### Update
+
+```typescript
+test("Update - update user", async () => {
+  const f0 = await loadFixtures(["user01"]);
+
+  await UserModel.save([
+    {
+      ...f0.user01,
+      username: "updated_username",
+    },
+  ]);
+
+  const f1 = await loadFixtures(["user01"]);
+  expect(f1.user01.username).toBe("updated_username");
+});
+```
+
+### Error Tests
+
+```typescript
+test("error when fetching non-existent user", async () => {
+  await expect(UserModel.findById("A", 99999)).rejects.toThrow("not found");
+});
+
+test("unresolved reference error", async () => {
+  const ub = new UpsertBuilder();
+  const companyRef = ub.register("companies", { name: "Test" });
+  ub.register("departments", { company_id: companyRef, name: "Dept" });
+
+  // attempt upsert in wrong order
+  await expect(ub.upsert(wdb, "departments")).rejects.toThrow(/unresolved reference/);
+});
+```
+
+## Test Structuring Patterns
+
+```typescript
+describe("UpsertBuilder", () => {
+  describe("A. Basic registration (register)", () => {
+    test("register() returns UBRef", async () => {
+      /* ... */
+    });
+    test("multiple register() calls accumulate rows", async () => {
+      /* ... */
+    });
+  });
+
+  describe("B. Table management", () => {
+    test("basic behavior of getTable()/hasTable()", async () => {
+      /* ... */
+    });
+  });
+
+  describe("C. Upsert execution", () => {
+    test("upsert() - insert new row", async () => {
+      /* ... */
+    });
+    test("upsert() - update existing row", async () => {
+      /* ... */
+    });
+    test("insertOnly() - insert only", async () => {
+      /* ... */
+    });
+  });
+
+  describe("D. Error handling", () => {
+    test("upsert on non-existent table → empty array", async () => {
+      /* ... */
+    });
+    test("unresolved reference → error", async () => {
+      /* ... */
+    });
+  });
+});
+```
+
+## File Structure
+
+```
+api/src/testing/
+├── fixture.ts       # createFixtureLoader definition
+├── global.ts        # globalSetup (dotenv, setup export)
+├── setup-mocks.ts   # global Mock configuration
+├── test-helpers.ts  # test utility functions
+├── expect-query.ts  # SQL query validation helper
+└── expect-ub.ts     # UpsertBuilder validation helper
+```