sonamu 0.10.4 → 0.10.6

package/src/skills/sonamu/testing.md

@@ -1,2163 +0,0 @@
----
-name: sonamu-testing
-description: Writing Sonamu tests. bootstrap, test/testAs functions, Fixture creation, Naite.get() assertions, expectQuery/expectUB helpers, Mock patterns. Use when writing or structuring test code for Models and APIs.
----
-
-# Sonamu Test System
-
-Sonamu provides a Vitest-based test environment. Each test is isolated in a transaction and automatically rolled back.
-
-**Example project**: `sonamu/examples/miomock` - reference for real test code
-
-**WARNING: Projects with 10 or more entities must use a batch strategy** (see "Large-Scale Project Strategy" below)
-
-**Reference documents**:
-
-- **Fixture CLI commands**: `fixture-cli.md` - fixture gen/fetch/explore usage, 3-Tier DB structure
-- **Fixture creation tips**: "Fixture Data Creation Tips" section at the bottom of this document, or the "Practical Tips" section in `fixture-cli.md`
-
----
-
-## Quick Start - Getting Started with Tests Quickly
-
-**Prerequisites**: scaffolding completed, nullable field handling in types.ts completed
-
-### Step 1: Extend test-helpers.ts
-
-```typescript
-// packages/api/src/application/__tests__/test-helpers.ts
-
-import { User, UserSaveParams } from "../user/user.types";
-import { Post, PostSaveParams } from "../post/post.types";
-import { Comment, CommentSaveParams } from "../comment/comment.types";
-import UserModel from "../user/user.model";
-import PostModel from "../post/post.model";
-import CommentModel from "../comment/comment.model";
-
-// User helper
-export async function createTestUser(params?: Partial<UserSaveParams>): Promise<number> {
-  const user: UserSaveParams = {
-    email: `test-${Date.now()}@example.com`,
-    name: "Test User",
-    ...params,
-  };
-  const [id] = await UserModel.save([user]);
-  return id;
-}
-
-// User with dependencies (dependency chain)
-export async function createTestUserWithDeps() {
-  const userId = await createTestUser();
-  return { userId };
-}
-
-// Post helper
-export async function createTestPost(
-  authorId: number,
-  params?: Partial<PostSaveParams>,
-): Promise<number> {
-  const post: PostSaveParams = {
-    author_id: authorId,
-    title: "Test Post",
-    content: "Test content",
-    ...params,
-  };
-  const [id] = await PostModel.save([post]);
-  return id;
-}
-
-// Post with dependencies
-export async function createTestPostWithDeps() {
-  const { userId } = await createTestUserWithDeps();
-  const postId = await createTestPost(userId);
-  return { userId, postId };
-}
-
-// Comment helper
-export async function createTestComment(
-  postId: number,
-  authorId: number,
-  params?: Partial<CommentSaveParams>,
-): Promise<number> {
-  const comment: CommentSaveParams = {
-    post_id: postId,
-    author_id: authorId,
-    content: "Test comment",
-    ...params,
-  };
-  const [id] = await CommentModel.save([comment]);
-  return id;
-}
-
-// Comment with dependencies
-export async function createTestCommentWithDeps() {
-  const { userId, postId } = await createTestPostWithDeps();
-  const commentId = await createTestComment(postId, userId);
-  return { userId, postId, commentId };
-}
-```
-
-**CRITICAL patterns**:
-
-- `createTestX()`: basic creation helper (overridable via params)
-- `createTestXWithDeps()`: helper that automatically handles dependencies (creates all required data together)
-- FK fields use the `_id` suffix (`author_id`, `post_id`)
-- Returns: primarily returns ID; WithDeps returns an object with multiple IDs
-
-**CRITICAL: All required fields must be included!**
-
-Sonamu's `ubUpsert` uses PostgreSQL's `ON CONFLICT ... DO UPDATE` query.
-Even for updates, **all required fields (fields with NOT NULL constraints)** must be included.
-
-When required fields are missing:
-
-```typescript
-// BAD - missing required field content
-const post: PostSaveParams = {
-  author_id: authorId,
-  title: "Test",
-  // content missing! → ubUpsert ON CONFLICT UPDATE attempts to set NULL → DB error
-};
-// Error: null value in column "content" violates not-null constraint
-```
-
-### Distinguishing Required vs Optional Fields
-
-**1. Check entity.json**
-
-```json
-// post.entity.json
-{
-  "props": [
-    { "name": "id", "type": "integer" }, // auto-generated - exclude
-    { "name": "title", "type": "string", "length": 255 }, // required! (no nullable)
-    { "name": "content", "type": "string" }, // required! (no nullable)
-    { "name": "category", "type": "string", "nullable": true }, // optional (nullable)
-    { "name": "author_id", "type": "integer" }, // required! (FK, no nullable)
-    { "name": "view_count", "type": "integer", "dbDefault": "0" }, // required but has DB default
-    { "name": "created_at", "type": "date", "dbDefault": "CURRENT_TIMESTAMP" } // automatic
-  ]
-}
-```
-
-**Required fields**: Fields **without** `nullable: true`
-
-- `title`, `content`, `author_id`
-- **Must** provide default values in test-helpers.ts
-
-**Optional fields**: Fields **with** `nullable: true`
-
-- `category`
-- Can be omitted in test-helpers.ts
-
-**Excluded fields**:
-
-- `id`: auto-increment (auto-generated on save)
-- `created_at`: automatically set by dbDefault
-- `view_count`: automatically set by dbDefault="0"
-
-**2. Write test-helpers.ts**
-
-```typescript
-export async function createTestPost(
-  authorId: number,
-  params?: Partial<PostSaveParams>,
-): Promise<number> {
-  const post: PostSaveParams = {
-    // Required fields must be included (fields without nullable)
-    author_id: authorId,
-    title: "Test Post", // required!
-    content: "Test content", // required!
-
-    // Optional fields can be omitted (fields with nullable: true)
-    // category: null,  // can be omitted
-
-    // Fields with dbDefault can also be omitted
-    // view_count: 0,  // can be omitted since dbDefault="0"
-
-    ...params, // allow override
-  };
-  const saved = await PostModel.save(post);
-  return saved.id;
-}
-```
-
-**Rule summary**:
-
-1. Fields without `nullable: true` in entity.json = required fields
-2. Required fields **must** have default values in test-helpers.ts
-3. `id`, `created_at`, fields with `dbDefault` can be excluded
-4. Required fields are also needed for ubUpsert's ON CONFLICT UPDATE
-
-### Step 2: Write the test file
-
-```typescript
-// packages/api/src/application/post/__tests__/post.test.ts
-
-import { bootstrap } from "sonamu";
-import { describe, test, expect, vi } from "vitest";
-import PostModel from "../post.model";
-import { createTestPostWithDeps } from "../../__tests__/test-helpers";
-
-bootstrap(vi); // CRITICAL: required!
-
-describe("PostModel", () => {
-  describe("A. Create", () => {
-    test("create post", async () => {
-      const { userId, postId } = await createTestPostWithDeps();
-
-      const post = await PostModel.findById(postId, ["A"]);
-      expect(post.id).toBe(postId);
-      expect(post.author_id).toBe(userId);
-    });
-  });
-
-  describe("B. Read", () => {
-    test("findById - Subset A", async () => {
-      const { postId } = await createTestPostWithDeps();
-
-      const post = await PostModel.findById(postId, ["A"]);
-      expect(post.id).toBe(postId);
-      expect(post).toHaveProperty("title");
-      expect(post).toHaveProperty("content");
-    });
-
-    test("findMany - list query", async () => {
-      await createTestPostWithDeps();
-      await createTestPostWithDeps();
-
-      const { rows } = await PostModel.findMany({ num: 10 });
-      expect(rows.length).toBeGreaterThanOrEqual(2);
-    });
-  });
-
-  describe("C. Update", () => {
-    test("update post", async () => {
-      const { postId } = await createTestPostWithDeps();
-
-      await PostModel.save([
-        {
-          id: postId,
-          title: "Updated Title",
-        },
-      ]);
-
-      const updated = await PostModel.findById("A", postId);
-      expect(updated.title).toBe("Updated Title");
-    });
-  });
-
-  describe("D. Delete", () => {
-    test("delete post", async () => {
-      const { postId } = await createTestPostWithDeps();
-
-      await PostModel.del(postId);
-
-      const post = await PostModel.findById(postId, ["A"]);
-      expect(post).toBeNull();
-    });
-  });
-
-  describe("E. Business Logic", () => {
-    test("full process from post creation to adding a comment", async () => {
-      // 1. create post
-      const { userId, postId } = await createTestPostWithDeps({
-        title: "New Post",
-        content: "Content",
-      });
-
-      // 2. another user writes a comment
-      const commenterId = await createTestUser();
-      const commentId = await createTestComment(postId, commenterId, {
-        content: "Great post!",
-      });
-
-      // 3. fetch post (with comments)
-      const post = await PostModel.findById(postId, ["A"]);
-      expect(post.comments).toHaveLength(1);
-      expect(post.comments[0].id).toBe(commentId);
-    });
-  });
-});
-```
-
-**Pattern summary**:
-
-- `bootstrap(vi)` call is required
-- `describe` + `test` pattern (order: A. Create, B. Read, C. Update, D. Delete, E. Business Logic)
-- Use `createTestXWithDeps()` helper to automatically resolve dependencies
-- The Business Logic section is the most important! (implements real business scenarios)
-
-### Step 3: Run tests
-
-```bash
-# Start dev server if it's down
-pnpm sonamu dev
-
-# Tests during development (default)
-pnpm sonamu test
-pnpm sonamu test user.model
-```
-
-**Done!** See the sections below for detailed information.
-
----
-
-## Pre-Test Writing Checklist
-
-- [ ] **Confirm entity design is complete** - `pnpm db:migration` and `pnpm scaffolding` completed without errors
-- [ ] **Plan test writing** - group entities by business process (→ see "Test Writing Plan" below)
-- [ ] **Handle nullable fields in types.ts (FIRST!)** - immediately after entity creation, apply partial + extend handling for nullable fields (→ see "Tasks to Do Immediately After Entity Creation" below)
-- [ ] **Prepare Seed Data** - base data required due to FK constraints (→ see "minimum seed data" in database.md)
-- [ ] **Test helper functions** - prepare helpers for handling complex entity dependencies
-- [ ] **For 10 or more entities** - plan batch strategy (see "Large-Scale Project Strategy" below)
-
-## Core Test Writing Principles
-
-### 1. Verify Actual Structure First
-
-**CRITICAL: Always verify the actual entity structure before planning tests.**
-
-Before writing tests, you must verify the following:
-
-```typescript
-// STEP 1: Check entity.json
-// - actual field names and types
-// - nullable status
-// - enum value list
-// - relation structure
-
-// STEP 2: Check types.ts
-// - partial settings in SaveParams
-// - nullish handling for nullable fields
-// - _ids arrays for ManyToMany relations
-
-// STEP 3: Check sonamu.generated.ts
-// - Enum type definitions
-// - Subset type structure
-// - BaseSchema structure
-```
-
-**Wrong approach:**
-
-```typescript
-// BAD - writing tests based on guesses
-test("create user", async () => {
-  const [userId] = await UserModel.save([
-    {
-      name: "Test",
-      status: "active", // may actually be "normal"
-      role: "user", // may actually be "normal"
-    },
-  ]);
-});
-```
-
-**Correct approach:**
-
-```typescript
-// GOOD - write after checking entity.json
-// 1. Check user.entity.json:
-//    - role: enum ["admin", "normal", "guest"]
-//    - status: enum ["active", "inactive"] with dbDefault: "active"
-//    - name: string (required)
-//    - email: string (nullable)
-
-// 2. Check user.types.ts:
-//    - status, email are partial in SaveParams
-
-// 3. Write test
-test("create user", async () => {
-  const [userId] = await UserModel.save([
-    {
-      name: "Test",
-      role: "normal", // exact enum value from entity.json
-      // status can be omitted since it has dbDefault
-      // email can be omitted since it's nullable
-    },
-  ]);
-});
-```
-
-### 2. Understanding Subset Structure
-
-**Access nested relations using dot notation.**
-
-```typescript
-// Check Subset definition in entity.json
-{
-  "subsets": {
-    "A": [
-      "id",
-      "title",
-      "evaluation_form.id",           // BelongsToOne relation
-      "evaluation_form.title",
-      "evaluation_form.category.id",  // nested relation
-      "evaluation_form.category.name"
-    ]
-  }
-}
-
-// Access in tests
-test("fetch evaluation item", async () => {
-  const { itemId } = await createTestEvaluationItemWithDeps();
-
-  const item = await EvaluationItemModel.findById("A", itemId);
-
-  // CORRECT - nested access via dot notation
-  expect(item.evaluation_form.id).toBe(formId);
-  expect(item.evaluation_form.category.name).toBe("Competency Evaluation");
-
-  // WRONG - attempting direct FK access
-  // expect(item.evaluation_form_id).toBe(formId);  // type error!
-});
-```
-
-**Important rules:**
-
-- FK of BelongsToOne relation is defined as `relation.id` form in Subset
-- Access in tests as `entity.relation.field` form
-- Direct `entity.relation_id` access is not possible (not included in Subset)
-
-### 3. Handling DECIMAL Types
-
-**DECIMAL types are returned from PostgreSQL with a `.00` suffix.**
-
-```typescript
-// entity.json
-{
-  "props": [
-    { "name": "salary", "type": "number", "precision": 10, "scale": 2 }
-  ]
-}
-
-// Generated in migration
-table.decimal("salary", 10, 2);  // DECIMAL(10,2)
-
-// Writing tests
-test("fetch salary info", async () => {
-  const [userId] = await UserModel.save([{
-    name: "Test",
-    salary: 75000,  // input: number
-  }]);
-
-  const user = await UserModel.findById("A", userId);
-
-  // WRONG - exact comparison may fail
-  // expect(user.salary).toBe(75000);  // DB may return "75000.00"
-
-  // CORRECT - pattern matching with toMatch()
-  expect(String(user.salary)).toMatch(/^75000(\.00)?$/);
-
-  // Or convert to number and compare
-  expect(Number(user.salary)).toBe(75000);
-
-  // Or range check
-  expect(user.salary).toBeGreaterThanOrEqual(74999.99);
-  expect(user.salary).toBeLessThanOrEqual(75000.01);
-});
-```
-
-**DECIMAL type comparison patterns:**
-
-```typescript
-// Pattern 1: string pattern matching
-expect(String(value)).toMatch(/^1234\.56$/);
-expect(String(value)).toMatch(/^1234(\.56)?$/); // .56 optional
-
-// Pattern 2: convert to number and compare
-expect(Number(value)).toBe(1234.56);
-
-// Pattern 3: range check (considering floating point errors)
-expect(value).toBeCloseTo(1234.56, 2); // up to 2 decimal places
-
-// Pattern 4: toMatchObject (when comparing objects)
-expect(result).toMatchObject({
-  salary: expect.any(Number), // type check only
-});
-```
-
-## 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 Writing Plan
-
-### Planning Based on Entity Design Prompt
-
-After entity design is complete (confirming migration + scaffolding succeed), group tests according to **the business processes and data flows specified at the time of entity design**.
-
-**CRITICAL:** Group tests by **business flow units**, not by simple alphabetical order or individual entities.
-
-### Step 1: Re-examine the Entity Design Prompt
-
-Extract the following from the prompt written at the time of the design request:
-
-- Business process flow
-- Relationships between entities (relations)
-- Data creation order
-- Key usage scenarios
-
-### Step 2: Group by Business Process
-
-Group entities by **business flow units**, not simple priority.
-
-**Customer consultation system example:**
-
-```
-Group 1: Core Infrastructure
-Organization (related agency)
-└─ User
-   └─ LoginHistory
-
-Business flow: register agency → create user → login
-Test order: Organization → User → LoginHistory
-
-Group 2: Damage Type Management
-DamageType (self-referencing)
-└─ CounterMeasure
-
-Business flow: build damage type hierarchy → write countermeasures for each type
-Test order: DamageType → CounterMeasure
-
-Group 3: Consultation Process (core business)
-User (applicant) + User (counselor) + DamageType
-└─ Consultation
-   ├─ ConsultationChannelLog
-   └─ ConsultationHistory
-
-Business flow:
-1. Applicant submits consultation request
-2. Assign counselor
-3. Classify damage type
-4. Communication by channel (online/phone/SMS/KakaoTalk)
-5. Record status change history
-
-Test order: Consultation → ConsultationChannelLog → ConsultationHistory
-
-Group 4: Content Management (independent)
-FAQ
-Banner
-Material
-Notice
-
-Business flow: independent CRUD for each
-Test order: any order (can be written in parallel)
-```
-
-### Step 3: Work Order per Group
-
-**For each group:**
-
-1. **Modify types.ts** - handle nullable fields for all entities in the group at once
-2. **Extend test-helpers.ts** - write helper functions for entities in the group together
-3. **Write test files** - write in dependency order within the group
-4. **Business Logic tests** - implement real business scenarios (the key!)
-5. **Verify tests pass** - proceed to next group
-
-**test-helpers.ts example (considering dependency chains):**
-
-```typescript
-// Write helpers considering dependency chains
-export async function createTestUserWithDeps() {
-  const organizationId = await createTestOrganization();
-  const userId = await createTestUser(organizationId);
-  return { organizationId, userId };
-}
-
-export async function createTestConsultationWithDeps() {
-  const { userId: applicantId } = await createTestUserWithDeps({
-    role: "applicant",
-  });
-  const { userId: counselorId } = await createTestUserWithDeps({
-    role: "counselor",
-  });
-  const damageTypeId = await createTestDamageType(null);
-  const consultationId = await createTestConsultation(applicantId, counselorId, damageTypeId);
-  return { applicantId, counselorId, damageTypeId, consultationId };
-}
-```
-
-### Step 4: Business Logic Tests (the key!)
-
-**IMPORTANT:** The E. Business Logic section is the most important.
-
-In this section:
-
-- Implement **real business scenarios** specified in the entity design prompt
-- Test **interactions** between entities
-- Validate **data flows**
-
-This is what differentiates it from simple CRUD tests, and it's **the core that validates design intent**.
-
-**Business Logic test example (consultation process):**
-
-```typescript
-describe("E. Business Logic", () => {
-  test("full process from consultation submission to completion", async () => {
-    // 1. submit consultation + create dependencies
-    const { consultationId, counselorId } = await createTestConsultationWithDeps();
-    // 2. record channel logs (online submission, phone consultation)
-    await createTestConsultationChannelLog(consultationId, {
-      channel: "online",
-    });
-    await createTestConsultationChannelLog(consultationId, {
-      channel: "phone",
-    });
-    // 3. record status history
-    await createTestConsultationHistory(consultationId, counselorId, {
-      status: "consulting",
-    });
-    // 4. complete consultation
-    await ConsultationModel.save([{ id: consultationId, status: "completed" }]);
-    // 5. verify: status, 2 channel logs, history
-    const c = await ConsultationModel.findById("A", consultationId);
-    expect(c.status).toBe("completed");
-  });
-});
-```
-
-### Notes
-
-**DO:**
-
-- Always reference the entity design prompt
-- Group by business process flow
-- Test order that considers dependency order
-- Business Logic tests based on real usage scenarios
-- Clearly implement dependency chains in test-helpers
-
-**DON'T:**
-
-- Write tests in simple alphabetical order
-- Only test entities individually (missing integration perspective)
-- Set priorities unrelated to business flow
-- Write tests that ignore the intent of the entity design
-
-### Checklist per Group
-
-When test writing for a process group is complete:
-
-- [ ] Nullable field handling in types.ts completed for all entities in the group
-- [ ] test-helpers written reflecting dependency chains within the group
-- [ ] Module test file written for each entity in the group
-- [ ] **Key business scenarios included in Business Logic tests**
-- [ ] All tests pass confirmed (`pnpm sonamu test`)
-- [ ] Proceed to next group
-
-## Tasks to Do Immediately After Entity Creation
-
-### Handling nullable Fields in types.ts (Required)
-
-After creating an entity and generating types.ts with `sonamu generate`, immediately handle nullable fields **before writing tests**.
-
-#### Work Order
-
-1. Run `sonamu generate`
-2. Check the generated `*.types.ts` file
-3. Apply partial + extend + nullish handling for nullable fields
-4. Start writing tests
-
-#### Fields to Process
-
-- All fields with `nullable: true`
-- Fields with `dbDefault` (`.optional().default(value)`)
-- FK relation fields that are nullable
-
-#### Practical Example
-
-**STEP 1: File generated after running sonamu generate**
-
-```typescript
-// faq.types.ts (auto-generated)
-import type { z } from "zod"; // WRONG: type import
-import { FAQBaseListParams, FAQBaseSchema } from "../sonamu.generated";
-
-export const FAQListParams = FAQBaseListParams;
-export type FAQListParams = z.infer<typeof FAQListParams>;
-
-export const FAQSaveParams = FAQBaseSchema.partial({
-  id: true,
-  created_at: true,
-  updated_at: true,
-});
-export type FAQSaveParams = z.infer<typeof FAQSaveParams>;
-```
-
-**STEP 2: Immediate fix (nullable fields + Zod import handling)**
-
-```typescript
-// faq.types.ts (fix complete)
-import { z } from "zod"; // CORRECT: change to regular import
-import { FAQBaseListParams, FAQBaseSchema } from "../sonamu.generated";
-
-export const FAQListParams = FAQBaseListParams;
-export type FAQListParams = z.infer<typeof FAQListParams>;
-
-export const FAQSaveParams = FAQBaseSchema.partial({
-  id: true,
-  created_at: true,
-  updated_at: true,
-  // add nullable fields
-  category: true,
-  order_num: true,
-}).extend({
-  // redefine nullable fields as nullish
-  category: z.string().nullish(), // string | null | undefined
-  order_num: z.number().nullish(), // number | null | undefined
-  updated_at: z.date().nullish(), // date | null | undefined
-});
-
-export type FAQSaveParams = z.infer<typeof FAQSaveParams>;
-```
-
-#### Why Is This Necessary?
-
-**Problem:** Zod's `nullable()` gives `T | null` but it's still required.
-
-```typescript
-// entity.json
-{ "name": "category", "type": "string", "nullable": true }
-
-// Generated BaseSchema
-z.object({
-  category: z.string().nullable(),  // string | null (required!)
-})
-
-// applying partial only
-.partial({ category: true })  // category?: string | null
-
-// WRONG: undefined cannot be assigned to string | null
-const [id] = await FAQModel.save([{
-  question: "Question",
-  answer: "Answer",
-  // omitting category causes type error!
-}]);
-```
-
-**Solution:** Combination of `partial()` + `extend()` + `nullish()`
-
-```typescript
-// CORRECT: proper handling
-FAQBaseSchema.partial({ category: true }).extend({
-  category: z.string().nullish(),
-}); // string | null | undefined
-
-// Can freely omit in tests
-const [id] = await FAQModel.save([
-  {
-    question: "Question",
-    answer: "Answer",
-    // category can be omitted!
-  },
-]);
-```
-
-#### Application Criteria
-
-| Field type                       | Handling                        |
-| -------------------------------- | ------------------------------- |
-| `id`, `created_at`, `updated_at` | Always partial (auto-generated) |
-| Fields with `dbDefault`          | `.optional().default(value)`    |
-| Fields with `nullable: true`     | partial + extend + `.nullish()` |
-| Required fields                  | Excluded from partial           |
-
-#### Checklist
-
-- [ ] Change `import type { z }` to `import { z }`
-- [ ] Add nullable fields to partial
-- [ ] Redefine as nullish via extend
-- [ ] Use `.optional().default()` for dbDefault fields
-- [ ] Confirm required fields are excluded from partial
-
-**Detailed type safety guide:** See "TypeScript Type Safety" and "Type Safety Notes" sections below
-
-## TypeScript Type Safety
-
-### Optional Chaining Required When Indexing Arrays
-
-When accessing a property after indexing into an array, you must use optional chaining (`?.`).
-
-**Reason:**
-
-- Array indexing (`array[0]`, `array[1]`, etc.) can always return `undefined`
-- TypeScript infers the type of `array[0]` as `T | undefined`
-- Accessing a property without optional chaining causes a compile error
-
-**Wrong:**
-
-```typescript
-// Type error: Object is possibly 'undefined'
-expect(list.rows[0].title).toBe("test");
-expect(searchResults.rows[0].name).toContain("keyword");
-```
-
-**Correct:**
-
-```typescript
-// Use optional chaining
-expect(list.rows[0]?.title).toBe("test");
-expect(searchResults.rows[0]?.name).toContain("keyword");
-
-// Or verify existence first, then access
-expect(list.rows.length).toBeGreaterThanOrEqual(1);
-expect(list.rows[0].title).toBe("test"); // now safe
-```
-
-### Recommended Patterns
-
-When accessing array elements in test code:
-
-**Pattern 1: Use optional chaining**
-
-```typescript
-const result = await Model.findMany("A", { num: 10, page: 1 });
-expect(result.rows[0]?.field).toBe(expectedValue);
-```
-
-**Pattern 2: Verify length, then access**
-
-```typescript
-const result = await Model.findMany("A", { num: 10, page: 1 });
-expect(result.rows.length).toBeGreaterThanOrEqual(1);
-expect(result.rows[0].field).toBe(expectedValue); // type-safe
-```
-
-**Pattern 3: Optional chaining required when using find()**
-
-```typescript
-const list = await Model.findMany("A", { num: 10, page: 1 });
-const item = list.rows.find((r) => r.id === targetId);
-expect(item?.field).toBe(expectedValue); // find() can return undefined
-```
-
-### General Rules
-
-- Property access after array indexing: `array[0]?.property`
-- Results of `find()`, `filter()[0]`, etc.: always use `?.`
-- Nested object access: `obj.nested?.deep?.property`
-- Non-null assertion (`!`) only when certain
-
-## Model Basic Methods (Test Targets)
-
-Sonamu Model provides the following methods by default. Tests are written targeting these methods:
-
-| Method                     | Purpose                | Returns                          |
-| -------------------------- | ---------------------- | -------------------------------- |
-| `findById(subset, id)`     | Fetch single record    | `Promise<Subset>`                |
-| `findMany(subset, params)` | Fetch list             | `Promise<ListResult<Subset>>`    |
-| `save(rows)`               | Create/update (upsert) | `Promise<number[]>` (ids)        |
-| `del(ids)`                 | Delete                 | `Promise<number>` (delete count) |
-
-**Note:** It's `del`, not `delete`. This avoids JavaScript reserved words.
-
-## Large-Scale Project Strategy (10 or more entities)
-
-**CRITICAL: Do not work on all entities at once if a project has 10 or more entities.**
-
-### Problems
-
-- Working on 55 entities at once causes context confusion
-- Serious risk of errors such as modifying the wrong file or deleting required content
-- Cannot track relationships, lose direction while writing tests
-
-### Solution: Batch Work Units
-
-**Rule: Group related entities together and work in batches of 5–10**
-
-```
-Batch 1: User, Institution, Role related (5 entities)
-  → Tests complete → Commit
-
-Batch 2: Survey, Question, Response related (7 entities)
-  → Tests complete → Commit
-
-Batch 3: Report, Statistics related (6 entities)
-  → Tests complete → Commit
-```
-
-### Batch Grouping Criteria
-
-**Grouping by domain (recommended):**
-
-```
-Auth/Permissions: User, Role, Permission, Session
-Surveys: Survey, Question, Choice, Response
-Reports: Report, Chart, Export
-Administration: Institution, Department, Settings
-```
-
-**Grouping by dependencies:**
-
-```
-1st: Independent entities (User, Institution, etc.)
-2nd: Entities depending on 1st (Survey → Institution)
-3rd: Entities depending on 2nd (Question → Survey)
-```
-
-### Batch Work Process
-
-**For each batch:**
-
-1. List entities in the batch explicitly
-2. Write test helpers (createTest...)
-3. Complete tests for all entities
-4. Confirm all tests pass
-5. **Git commit, then proceed to next batch**
-
-**Between-batch checklist:**
-
-- [ ] All tests in current batch pass
-- [ ] Previous batch tests still pass (prevent regression)
-- [ ] Commit complete (establish rollback point)
-
-### Declare Before Starting Work
-
-**IMPORTANT: Declare explicitly before starting each batch**
-
-```
-"Starting batch 1: User, Institution, Role entities (5)
-- User: write user.model.test.ts
-- Institution: write institution.model.test.ts
-- Role: write role.model.test.ts
-Only work on files to be modified, do not touch other files
-Shall we proceed?"
-```
-
-### Warning Signs
-
-**Stop work immediately** if any of the following occur:
-
-- Attempting to modify entities outside the batch scope
-- Asking the same question repeatedly
-- Confusing entity relationships
-- Trying to re-modify files already completed
-
-## Running Tests
-
-**Principle: Use `pnpm sonamu test` during development.** Assume the dev server is always running. If the dev server is down, start it first with `pnpm sonamu dev`, then run tests. Use `pnpm test` only in CI environments.
-
-```bash
-# Check dev server (start if it's down)
-pnpm sonamu dev
-
-# Tests during development (default)
-pnpm sonamu test
-pnpm sonamu test user.model
-pnpm sonamu test user.model -p "findMany"
-
-# CI environments only
-pnpm test
-```
-
-### DevRunner — `sonamu test` (Default Test Execution Method)
-
-`sonamu test` runs tests through a Vitest Node API instance that resides inside the `sonamu dev` process. Instead of starting Vitest fresh each time, it reuses an already-initialized instance, making execution 3.2x faster, and it integrates with HMR so tests always run against the latest code immediately after source changes.
-
-#### Prerequisites
-
-**1. Enable devRunner in sonamu.config.ts:**
-
-```typescript
-export default defineConfig({
-  test: {
-    devRunner: {
-      enabled: true,
-      // routePrefix: "/__test__",   // optional, default value
-      // vitestConfigPath: undefined, // optional, default: vitest.config.ts (relative to api-root)
-    },
-  },
-});
-```
-
-Configuration type (`SonamuDevRunnerConfig`):
-
-- `enabled: boolean` — Whether to enable DevRunner (default: false)
-- `routePrefix?: string` — Test endpoint path prefix (default: `/__test__`)
-- `vitestConfigPath?: string` — vitest.config.ts path (relative to api-root)
-
-**2. Start the dev server:**
-
-```bash
-sonamu dev  # or pnpm dev
-```
-
-When the dev server starts, `DevVitestManager` is automatically initialized under the `isLocal() && devRunner.enabled` condition, and test endpoints are registered with Fastify.
-
-#### CLI Usage
-
-```bash
-# Run all tests
-sonamu test
-
-# Specify file (matched by partial filename — uses globTestSpecifications)
-sonamu test user.model
-
-# Multiple files
-sonamu test user.model order.model
-
-# Run specific test cases only (test name pattern)
-sonamu test user.model --pattern "findMany"
-sonamu test user.model -p "findMany"
-
-# Print Naite traces
-sonamu test user.model --traces
-sonamu test user.model -t
-
-# Combine file + pattern + trace
-sonamu test user.model -p "findMany" -t
-```
-
-Argument processing rules:
-
-- `--pattern` / `-p`: test name string filter (`setGlobalTestNamePattern` → `resetGlobalTestNamePattern` after execution)
-- `--traces` / `-t`: boolean flag, enables Naite trace output
-- Arguments not starting with `-`: treated as file list
-- Multiple files allowed
-- `ok: false` in server response is reflected as exit code 1
-
-**→ Naite traces, HMR integration, HTTP API, internal architecture, performance comparison, troubleshooting details: `testing-devrunner.md`**
-
-## sonamu.config.ts Test Configuration and Config Files
-
-**→ Configuration type definitions, DevRunner/parallel settings, activation conditions, parallel DB flow, vitest.config.ts/global.ts details: `testing-devrunner.md`**
-
-Key settings summary only:
-
-```typescript
-// sonamu.config.ts
-export default defineConfig({
-  test: {
-    devRunner: { enabled: true }, // required to use pnpm sonamu test
-    // parallel: true,              // optional: separate DB per worker
-    // maxWorkers: 4,               // optional: number of parallel workers
-  },
-});
-```
-
-## 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);
-});
-```
-
-## 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): `naite.md`**
-
-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);
-});
-```
-
-## 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
-```
-
-## Rules
-
-- `bootstrap(vi)` call required in all test files
-- Each test is automatically rolled back (test isolation)
-- Use `test` for unauthenticated tests, `testAs` for authenticated tests
-- Define fixtures with `createFixtureLoader` and load with `loadFixtures`
-- Use Naite to track and validate query/UpsertBuilder behavior
-- Recommend snapshot tests using `toMatchInlineSnapshot()`
-- Configure Mocks globally in `setup-mocks.ts` or use `vi.spyOn` within tests
-
-## Type Safety Notes
-
-### Zod Import Method
-
-**CRITICAL: Always use regular imports when importing Zod in test files.**
-
-```typescript
-// CORRECT - in test files
-import { z } from "zod";
-import { describe, expect, vi } from "vitest";
-
-// WRONG - runtime error when using type import
-import type { z } from "zod"; // error when test runs!
-```
-
-**Reason:** Because `z.infer<>` and Zod schemas are used directly in tests, the Zod object is needed at runtime.
-
-**Where this applies:**
-
-- `*.model.test.ts` - all test files
-- `test-helpers.ts` - helper files that use Zod schemas
-
-### Checking partial Settings in SaveParams
-
-When testing `Model.save()`, you must check the `SaveParams` partial settings in `*.types.ts`:
-
-```typescript
-// user.types.ts
-import { z } from "zod"; // regular import in types files too
-import { UserBaseSchema } from "../sonamu.generated";
-
-export const UserSaveParams = UserBaseSchema.partial({
-  id: true, // auto-generated
-  created_at: true, // auto-generated
-  updated_at: true, // auto-generated
-});
-export type UserSaveParams = z.infer<typeof UserSaveParams>;
-```
-
-### Nullable Field Handling Pattern
-
-**→ See "Tasks to Do Immediately After Entity Creation" section above** (partial + extend + nullish pattern)
-
-### Use Nullish Coalescing
-
-Nullish coalescing is required when a variable can be of type `T | undefined`:
-
-```typescript
-// WRONG: userId may be number | undefined
-const user = await UserModel.findById("A", userId);
-
-// CORRECT: guard against undefined with nullish coalescing
-const user = await UserModel.findById("A", userId ?? 0);
-```
-
-Especially be careful when using IDs created in a previous step:
-
-```typescript
-const [userId] = await UserModel.save([{ ... }]);
-
-// WRONG: userId is number | undefined
-const user = await UserModel.findById("A", userId);
-
-// CORRECT:
-const user = await UserModel.findById("A", userId ?? 0);
-```
-
-### SaveParams Import Location
-
-SaveParams types are exported from each entity's types.ts, not from sonamu.generated.
-
-**Wrong:**
-
-```typescript
-// test-helpers.ts
-import type { UserSaveParams, TaskSaveParams } from "../application/sonamu.generated"; // WRONG
-```
-
-**Correct:**
-
-```typescript
-// test-helpers.ts
-import type { UserSaveParams } from "../application/user/user.types";
-import type { TaskSaveParams } from "../application/task/task.types";
-```
-
-**Reason:**
-
-- sonamu.generated only exports BaseSchema and BaseListParams
-- SaveParams is defined with BaseSchema.partial() in each entity's types.ts
-
-## Practical Notes (Common Pitfalls)
-
-### 1. Fixture Data Preparation Required
-
-**Problem:** Tests fail without base data due to foreign key constraints
-
-**Solution:**
-
-```sql
--- database/scripts/seed-initial-data.sql
-INSERT INTO institutions (id, name, code) VALUES (1, 'HQ', 'HQ');
-INSERT INTO departments (id, name, institution_id) VALUES (1, 'Research', 1);
-INSERT INTO roles (id, code, name) VALUES (1, 'ADMIN', 'Administrator');
-```
-
-```bash
-# 1. apply seed data to test DB
-PGPASSWORD=1234 psql -h 0.0.0.0 -U postgres -d project_test -f database/scripts/seed-initial-data.sql
-
-# 2. create dump
-pnpm dump
-
-# 3. apply to fixture DB
-pnpm seed
-
-# 4. sonamu fixture sync (optional)
-pnpm sonamu fixture sync
-```
-
-### 2. SaveParams Type Design (Partial)
-
-**Problem 1:** Type error occurs when changing only some fields on update
-
-**Problem 2:** Type error occurs when receiving overrides as Partial in test helpers
-
-```typescript
-// WRONG - nullable fields not set to partial
-export const QuestionSaveParams = QuestionBaseSchema.partial({
-  id: true,
-  created_at: true,
-});
-
-// test-helpers.ts
-export async function createTestQuestion(
-  collectionId: number,
-  override?: Partial<QuestionSaveParams>,
-) {
-  const [id] = await QuestionModel.save([
-    {
-      content: "test question",
-      parent_id: null,
-      answer_group_id: null,
-      ...override, // type error: undefined cannot be assigned to null
-    },
-  ]);
-  return id;
-}
-```
-
-**Solution:** Set nullable/dbDefault fields to partial
-
-```typescript
-// api/src/application/user/user.types.ts
-export const UserSaveParams = UserBaseSchema.partial({
-  id: true, // needed for update
-  created_at: true, // dbDefault
-  password: true, // nullable
-  email: true, // nullable
-  phone: true, // nullable
-  user_type: true, // dbDefault
-  position_code: true, // nullable
-  position_name: true, // nullable
-  hire_date: true, // nullable
-  status: true, // dbDefault
-  department_id: true, // nullable relation
-});
-```
-
-**Application criteria:**
-
-- id, created_at, updated_at: always partial (auto-generated)
-- Fields with dbDefault: set to partial
-- FK fields with nullable: true: set to partial
-- Regular fields with nullable: true (e.g. description): set to partial
-
-**Key:** Required fields (employee_no, login_id, name, institution_id) are excluded from partial to maintain type safety
-
-### 3. Excluding Relation Fields on Update
-
-**Problem:** Subset includes relation objects, but SaveParams only has FK, causing errors
-
-```typescript
-// WRONG
-const user = await UserModel.findById("A", userId);
-await UserModel.save([{ ...user, status: "inactive" }]);
-// → "column 'department' does not exist" error
-```
-
-**Solution:** Exclude relation fields + explicitly add FK
-
-```typescript
-// CORRECT
-const user = await UserModel.findById("A", userId);
-const { institution, department, ...userData } = user;
-await UserModel.save([
-  {
-    ...userData,
-    institution_id: user.institution.id, // explicitly add FK
-    department_id: user.department?.id ?? null,
-    status: "inactive",
-  },
-]);
-```
-
-**Reason:** `UserSubsetA` includes `institution`, `department` objects, but does not include `institution_id`, `department_id` FKs
-
-### 4. ubUpsert is an Upsert Operation
-
-**Problem:** Unique constraint violation tests fail
-
-```typescript
-// failing test
-test("employee number must be unique", async () => {
-  await UserModel.save([{ employee_no: "001", ... }]);
-
-  // attempt to create with duplicate employee number
-  await expect(
-    UserModel.save([{ employee_no: "001", ... }])
-  ).rejects.toThrow();  // does not throw error, performs UPDATE instead
-});
-```
-
-**Cause:** Sonamu's `save()` uses `ubUpsert` → on conflict, performs UPDATE instead of throwing error
-
-**Solution:** Skip such tests
-
-```typescript
-test.skip("employee number must be unique (skipped because ubUpsert performs upsert)", async () => {
-  // ...
-});
-```
-
-### 5. testAs Usage
-
-**Problem:** Calling testAs inside test causes an error
-
-```typescript
-// WRONG
-test("permission test", async () => {
-  await testAs(adminUser, "description", async () => { ... });
-  // → "Calling the test function inside another test function is not allowed" error
-});
-
-// CORRECT - use as a replacement for test
-testAs(adminUser, "permission test", async () => {
-  const result = await UserModel.del([userId]);
-  expect(result).toBe(1);
-});
-```
-
-### 6. Validating Model Queries with Naite
-
-**Add Naite recording to Model:**
-
-```typescript
-// user.model.ts
-import { Naite } from "sonamu";
-
-async findMany(...) {
-  // ... build qb ...
-
-  // record query for testing
-  Naite.t("esq-query", qb.toQuery());
-
-  return this.executeSubsetQuery({ ... });
-}
-```
-
-**Validate in test:**
-
-```typescript
-test("should not have limit when num: 0", async () => {
-  await UserModel.findMany("A", { num: 0, page: 1 });
-
-  expect(Naite.get("esq-query").first()).not.contain("limit");
-  expect(Naite.get("esq-query").first()).not.contain("offset");
-});
-```
-
-### 7. Consider Multilingual Error Messages
-
-```typescript
-// WRONG: only validates English message
-await expect(UserModel.findById("A", 99999)).rejects.toThrow("not found");
-
-// CORRECT: partial match on actual error message
-await expect(UserModel.findById("A", 99999)).rejects.toThrow("does not exist");
-```
-
-### 8. pnpm Workspace and Vitest Instance Conflicts
-
-**Problem:** "Vitest failed to access its internal state" error
-
-**Cause:** When sonamu is connected via `link:`, sonamu and the project's vitest are installed at separate paths with different peer dependency combinations
-
-**Temporary fix (for testing):**
-
-```json
-// packages/api/package.json
-{
-  "dependencies": {
-    "sonamu": "0.8.0" // specify version instead of link
-  }
-}
-```
-
-**Fundamental fix:** Contact sonamu developers (framework internal issue)
-
-### 9. assert() for Truthy Checks
-
-```typescript
-import assert from "assert";
-
-test("create user", async () => {
-  const [userId] = await UserModel.save([{ ... }]);
-
-  // truthy check
-  assert(userId);
-
-  // userId is now safely inferred as number
-  const user = await UserModel.findById("A", userId);
-});
-```
-
-### 10. Create Test Data Directly
-
-**miomock convention:** Minimize fixtures, create data directly within tests
-
-```typescript
-// recommended pattern
-test("create user", async () => {
-  const [userId] = await UserModel.save([
-    {
-      employee_no: "2026001",
-      login_id: "testuser",
-      name: "Test User",
-      institution_id: 1,
-      // ... required fields
-    },
-  ]);
-
-  const user = await UserModel.findById("A", userId);
-  expect(user.name).toBe("Test User");
-});
-
-// Fixtures only for shared data
-const f = await loadFixtures(["institution01"]); // only for shared data like institutions
-```
-
-## Complex Entity Test Strategy
-
-When dependencies between entities are complex (Institution → Department → User → Task → TaskParticipant), use test helper functions.
-
-### Defining Test Helper Functions
-
-```typescript
-// api/src/testing/test-helpers.ts
-import assert from "assert";
-import { InstitutionModel } from "../application/institution/institution.model";
-import { DepartmentModel } from "../application/department/department.model";
-import { UserModel } from "../application/user/user.model";
-import { TaskModel } from "../application/task/task.model";
-
-// each helper requires only the minimum required fields and provides defaults for the rest
-let counter = 0;
-function uniqueId(prefix: string) {
-  return `${prefix}_${Date.now()}_${++counter}`;
-}
-
-export async function createTestInstitution(override?: Partial<InstitutionSaveParams>) {
-  const [id] = await InstitutionModel.save([
-    {
-      name: "Test Institution",
-      code: uniqueId("INST"),
-      ...override,
-    },
-  ]);
-  assert(id);
-  return id;
-}
-
-export async function createTestDepartment(
-  institutionId: number,
-  override?: Partial<DepartmentSaveParams>,
-) {
-  const [id] = await DepartmentModel.save([
-    {
-      name: "Test Department",
-      code: uniqueId("DEPT"),
-      dept_type: "division",
-      institution_id: institutionId,
-      is_active: true,
-      sort_order: 0,
-      ...override,
-    },
-  ]);
-  assert(id);
-  return id;
-}
-
-export async function createTestUser(institutionId: number, override?: Partial<UserSaveParams>) {
-  const [id] = await UserModel.save([
-    {
-      employee_no: uniqueId("EMP"),
-      login_id: uniqueId("login"),
-      name: "Test User",
-      institution_id: institutionId,
-      ...override,
-    },
-  ]);
-  assert(id);
-  return id;
-}
-
-export async function createTestTask(
-  principalInvestigatorId: number,
-  override?: Partial<TaskSaveParams>,
-) {
-  const [id] = await TaskModel.save([
-    {
-      task_no: uniqueId("TASK"),
-      title: "Test Task",
-      year: new Date().getFullYear(),
-      begin_date: new Date(),
-      end_date: new Date(Date.now() + 365 * 24 * 60 * 60 * 1000),
-      principal_investigator_id: principalInvestigatorId,
-      ...override,
-    },
-  ]);
-  assert(id);
-  return id;
-}
-
-// create the entire dependency chain at once
-export async function createTestTaskWithDeps(taskOverride?: Partial<TaskSaveParams>) {
-  const institutionId = await createTestInstitution();
-  const userId = await createTestUser(institutionId);
-  const taskId = await createTestTask(userId, taskOverride);
-  return { institutionId, userId, taskId };
-}
-
-export async function createTestUserWithDeps(userOverride?: Partial<UserSaveParams>) {
-  const institutionId = await createTestInstitution();
-  const userId = await createTestUser(institutionId, userOverride);
-  return { institutionId, userId };
-}
-```
-
-### Using in Tests
-
-```typescript
-import { createTestTaskWithDeps, createTestUser } from "../../testing/test-helpers";
-
-describe("TaskModel", () => {
-  // GOOD: concise with helper functions
-  test("Create - create with minimum required fields", async () => {
-    const { taskId } = await createTestTaskWithDeps();
-
-    const task = await TaskModel.findById("D", taskId);
-    expect(task.id).toBe(taskId);
-  });
-
-  // GOOD: customize specific fields
-  test("Create - create with specific status", async () => {
-    const { taskId } = await createTestTaskWithDeps({
-      status: "approved",
-      title: "Approved Task",
-    });
-
-    const task = await TaskModel.findById("D", taskId);
-    expect(task.status).toBe("approved");
-  });
-
-  // BAD: creating dependencies directly in every test (repetitive)
-  test("Create - direct creation (not recommended)", async () => {
-    const [institutionId] = await InstitutionModel.save([{ name: "...", code: "..." }]);
-    assert(institutionId);
-    const [userId] = await UserModel.save([{ ... }]);
-    assert(userId);
-    const [taskId] = await TaskModel.save([{ ... }]);
-    assert(taskId);
-    // ...
-  });
-});
-```
-
-### Subset → SaveParams Conversion Helper
-
-When modifying findById results and saving again, relations must be converted to FKs:
-
-```typescript
-// api/src/testing/test-helpers.ts
-
-// Task Subset A → SaveParams conversion
-export function taskToSaveParams(task: TaskSubsetA): TaskSaveParams {
-  const { program, project, principal_investigator, department, prev_task, ...rest } = task;
-
-  return {
-    ...rest,
-    program_id: program?.id ?? null,
-    project_id: project?.id ?? null,
-    principal_investigator_id: principal_investigator.id,
-    department_id: department?.id ?? null,
-    prev_task_id: prev_task?.id ?? null,
-  };
-}
-
-// generic helper (note: write directly if relation field names differ)
-export function relationToFk<T extends Record<string, any>>(
-  data: T,
-  relationFields: string[],
-): Record<string, any> {
-  const result: Record<string, any> = {};
-
-  for (const [key, value] of Object.entries(data)) {
-    if (relationFields.includes(key)) {
-      // relation → FK
-      result[`${key}_id`] = value?.id ?? null;
-    } else {
-      result[key] = value;
-    }
-  }
-
-  return result;
-}
-```
-
-### Simplifying Update Tests
-
-```typescript
-import { createTestTaskWithDeps, taskToSaveParams } from "../../testing/test-helpers";
-
-test("Update - update task info", async () => {
-  const { taskId } = await createTestTaskWithDeps();
-
-  const task = await TaskModel.findById("A", taskId);
-  await TaskModel.save([
-    {
-      ...taskToSaveParams(task),
-      title: "Updated Title",
-    },
-  ]);
-
-  const updated = await TaskModel.findById("A", taskId);
-  expect(updated.title).toBe("Updated Title");
-});
-```
-
-### Notes
-
-**Do not use beforeAll/beforeEach:**
-
-In sonamu's test environment, creating data with beforeAll/beforeEach may end up referencing sonamu internal code. Instead, call helper functions within each test.
-
-```typescript
-// WRONG: using beforeAll
-describe("TaskModel", () => {
-  let taskId: number;
-  beforeAll(async () => {
-    const result = await createTestTaskWithDeps();
-    taskId = result.taskId;
-  });
-
-  test("...", async () => {
-    // using taskId - may cause problems
-  });
-});
-
-// CORRECT: create in each test
-describe("TaskModel", () => {
-  test("...", async () => {
-    const { taskId } = await createTestTaskWithDeps();
-    // use taskId
-  });
-});
-```
-
----
-
-## Common Mistakes and Solutions
-
-### ubUpsert Does Not Throw Unique Constraint Errors
-
-**→ See "Practical Notes #4. ubUpsert is an Upsert Operation" above**
-
-### Transaction Isolation and Test Isolation
-
-Each test runs in an independent transaction so data is isolated. Even within the same test, data you created may not be immediately visible in queries.
-
-```typescript
-// BAD: expecting exact count may fail
-test("search by role name", async () => {
-  await createTestRole({ name: "AdminA" });
-  await createTestRole({ name: "AdminB" });
-
-  const { rows } = await RoleModel.findMany("A", {
-    keyword: "Admin",
-  });
-
-  // may not see 2 due to transaction isolation
-  expect(rows.length).toBe(2);
-});
-
-// GOOD: use unique identifier and flexible assertion
-test("search by role name", async () => {
-  // unique identifier to prevent conflicts
-  const testName = `SearchTest_${Date.now()}`;
-  await createTestRole({ name: `${testName}A` });
-  await createTestRole({ name: `${testName}B` });
-
-  const { rows } = await RoleModel.findMany("A", {
-    keyword: testName,
-  });
-
-  // verify at least 1
-  expect(rows.length).toBeGreaterThanOrEqual(1);
-  // content validation
-  expect(rows.some((r) => r.name.includes(testName))).toBe(true);
-});
-```
-
-**Patterns:**
-
-- Use unique identifiers: `Date.now()`, `uuid()`, etc. to prevent conflicts
-- Flexible assertions: use `toBeGreaterThanOrEqual(1)` instead of `toBe(2)`
-- Content validation: verify actual data matches rather than count
-
-### Conditional Validation for Sorting Tests
-
-Since not all data may be returned in sorting tests, use conditional validation:
-
-```typescript
-// BAD: assumes two items are always returned
-test("sort - newest ID first", async () => {
-  const id1 = await createTestRole({ name: "Role1" });
-  const id2 = await createTestRole({ name: "Role2" });
-
-  const { rows } = await RoleModel.findMany("A", {
-    orderBy: "id-desc",
-  });
-
-  const id2Index = rows.findIndex((r) => r.id === id2);
-  const id1Index = rows.findIndex((r) => r.id === id1);
-
-  // fails if either is missing
-  expect(id2Index).toBeLessThan(id1Index);
-});
-
-// GOOD: conditional validation
-test("sort - newest ID first", async () => {
-  const id1 = await createTestRole({ name: "Role1" });
-  const id2 = await createTestRole({ name: "Role2" });
-
-  const { rows } = await RoleModel.findMany("A", {
-    orderBy: "id-desc",
-  });
-
-  const testRoles = rows.filter((r) => [id1, id2].includes(r.id));
-  expect(testRoles.length).toBeGreaterThanOrEqual(1);
-
-  // only validate order when both roles are returned
-  if (testRoles.length === 2) {
-    const id2Index = rows.findIndex((r) => r.id === id2);
-    const id1Index = rows.findIndex((r) => r.id === id1);
-    expect(id2Index).toBeLessThan(id1Index);
-  }
-});
-```
-
-**Key:** Accept the uncertainty caused by transaction isolation, and only assert when validation is possible.
-
----
-
-## Fixture Data Creation Tips
-
-**→ Detailed guide (unique constraint handling, gen vs fetch selection, DB sequence reset, FixtureGenerator customization): `fixture-cli.md` "Practical Tips" section**