sonamu 0.10.7 → 0.10.9

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

@@ -1,185 +0,0 @@
-# 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

@@ -1,263 +0,0 @@
-# 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
-```