> ## Documentation Index > Fetch the complete documentation index at: https://sonamu.cartanova.ai/llms.txt > Use this file to discover all available pages before exploring further. # Naite Viewer > Visualizing test logs with VSCode Extension Learn how to use Naite Viewer, the VSCode Extension that visualizes logs recorded during test execution in real-time. ## Naite Viewer Overview During test execution Immediate log display Inter-process communication Fast transmission Separate socket files Independent operation On Extension startup Automatic socket creation ## What is Naite Viewer? **Naite Viewer** is a feature included in the Sonamu VSCode Extension that visualizes Naite logs recorded during test execution in real-time. Naite transmits all data recorded with `Naite.t()` during test execution to the VSCode Extension, allowing developers to visually track test flows. This is especially useful for complex business logic or situations involving multiple intertwined function calls. ### Key Features Immediately displays all logs recorded with `Naite.t()` during test execution in the VSCode panel. View structured logs without searching through the console. Automatically groups logs by test case. Also categorized by Suite, so you can quickly find desired logs even in large-scale tests. Displays the call location and full callstack information for each log. Click on a log to navigate directly to that code location. Filter logs from specific modules using wildcard patterns (`user:*`), or search log contents by keyword. ## Architecture ### 1. Unix Socket Communication Naite Viewer communicates with the test process through Unix Socket. This method allows direct inter-process communication without using the file system, making it fast and secure. ```mermaid theme={null} flowchart LR subgraph TestProcess["Test Process (Vitest)"] direction TB Test["test()"] --> Naite["Naite.t()"] Naite --> Reporter["NaiteReporter"] end subgraph VSCodeExt["VSCode Extension"] direction TB Socket["Socket Server"] --> Viewer["Naite Viewer Panel"] end Reporter -->|"Unix Socket
~/.sonamu/naite-{hash}.sock"| Socket style TestProcess fill:#e3f2fd style VSCodeExt fill:#fff3e0 ``` **Benefits of socket communication**: * **Fast transmission**: Much faster IPC (Inter-Process Communication) than HTTP or files * **Real-time**: Logs are delivered to Extension immediately as tests run * **Isolation**: Independent sockets per project prevent conflicts **Socket path rules**: ```bash theme={null} ~/.sonamu/naite-{hash}.sock ``` `{hash}` is the first 8 characters of the MD5 hash of the `sonamu.config.ts` path. ```powershell theme={null} \\.\pipe\naite-{hash} ``` Uses Windows Named Pipe. Each project generates a unique hash based on the absolute path of the `sonamu.config.ts` file: ```typescript theme={null} import { createHash } from "crypto"; const configPath = "/project/api/src/sonamu.config.ts"; const hash = createHash("md5") .update(configPath) .digest("hex") .slice(0, 8); // Example: "a1b2c3d4" // Final socket path: ~/.sonamu/naite-a1b2c3d4.sock ``` This way, even when running multiple Sonamu projects simultaneously, each uses an independent socket so logs don't get mixed. ### 2. Message Protocol Three types of messages are transmitted between the test process and Extension. #### run/start - Test Run Start Sent when a test run starts. The Extension clears all existing logs and prepares for a new test run upon receiving this message. ```typescript Message Format theme={null} { type: "run/start", startedAt: "2025-01-08T12:34:56.789Z" } ``` ```typescript Send Timing theme={null} // Vitest Reporter's onTestRunStart() export const NaiteVitestReporter = { async onTestRunStart() { await NaiteReporter.startTestRun(); } }; // Or beforeAll() beforeAll(async () => { await NaiteReporter.startTestRun(); }); ``` In watch mode, when you modify a file, tests are re-run, and a `run/start` message is sent each time, reinitializing the Viewer. #### test/result - Test Result Sent each time a test case completes. Includes the test result along with Naite logs (traces). ```typescript Message Format theme={null} { type: "test/result", receivedAt: "2025-01-08T12:34:57.123Z", suiteName: "UserModel", suiteFilePath: "/Users/.../user.model.test.ts", testName: "create user", testFilePath: "/Users/.../user.model.test.ts", testLine: 15, status: "pass", duration: 123, traces: [ { key: "user:create:input", value: { username: "john" }, filePath: "/Users/.../user.model.test.ts", lineNumber: 20, at: "2025-01-08T12:34:57.100Z" } ] } ``` ```typescript Send Timing theme={null} // afterEach in bootstrap.ts afterEach(async ({ task }) => { await NaiteReporter.reportTestResult({ suiteName: task.suite?.name ?? "(no suite)", testName: task.name, status: task.result?.state ?? "pass", traces: task.meta?.traces ?? [], // ... other metadata }); }); ``` **Included information**: * **Test metadata**: Suite name, file path, line number * **Test result**: Pass/fail status, duration, error info * **Naite traces**: All logs recorded with `Naite.t()` #### run/end - Test Run End Sent when all tests complete. The Extension recognizes the test run has ended with this message. ```typescript Message Format theme={null} { type: "run/end", endedAt: "2025-01-08T12:34:58.789Z" } ``` ```typescript Send Timing theme={null} // Vitest Reporter's onTestRunEnd() export const NaiteVitestReporter = { async onTestRunEnd() { await NaiteReporter.endTestRun(); } }; ``` ### 3. Transmission Flow Let's look at the order in which messages are sent throughout the test execution process. ```mermaid theme={null} sequenceDiagram participant Test as Test Code participant Reporter as NaiteReporter participant Socket as Unix Socket participant Extension as VSCode Extension Test->>Reporter: beforeAll() / onTestRunStart() Reporter->>Socket: run/start Socket->>Extension: Test run started Extension->>Extension: Clear existing logs loop Each test case Test->>Test: test() execution Test->>Test: Naite.t() call Test->>Reporter: afterEach() Reporter->>Reporter: Collect task.meta.traces Reporter->>Socket: test/result + traces Socket->>Extension: Display test result end Test->>Reporter: afterAll() / onTestRunEnd() Reporter->>Socket: run/end Socket->>Extension: Test run complete Reporter->>Reporter: Close socket connection ``` ```typescript theme={null} // 1. Test start - Socket connection and run/start send beforeAll(async () => { await NaiteReporter.startTestRun(); // → send({ type: "run/start" }) }); // 2. Test execution - Naite log collection test("create user", async () => { Naite.t("user:create:input", { username: "john" }); const { user } = await userModel.create({ username: "john" }); Naite.t("user:create:output", { userId: user.id }); // afterEach runs after test ends }); // 3. Test end - traces collection and send afterEach(async ({ task }) => { // Collect all Naite logs with getAllTraces() task.meta.traces = Naite.getAllTraces(); // Send to Extension await NaiteReporter.reportTestResult({ testName: task.name, status: task.result?.state, traces: task.meta.traces, // ... }); // → send({ type: "test/result", traces: [...] }) }); // 4. Full run end - run/end send and socket close afterAll(() => { await NaiteReporter.endTestRun(); // → send({ type: "run/end" }) // → socket.end() }); ``` **Buffering Mechanism**: If the Extension hasn't started yet or socket connection is delayed, NaiteReporter stores messages in a buffer and sends them all at once when connection succeeds. This allows you to see previous test logs even if you start the Extension late. ## Installation and Setup ### 1. Extension Installation 1. Click the Extensions icon in VSCode's left sidebar 2. Search for "Sonamu" 3. Click the Install button After installation, if the Sonamu icon appears in VSCode's bottom status bar, it's properly activated. ### 2. Auto Connection The Extension automatically starts the socket server when it runs: Finds the `sonamu.config.ts` file in the current workspace. Generates an MD5 hash (first 8 characters) from the absolute path of `sonamu.config.ts`. Starts a Unix Socket server at `~/.sonamu/naite-{hash}.sock`. NaiteReporter connects to this socket when tests run. The Extension creates sockets based on project path, so you must **open the project folder directly** for it to work properly. Opening a parent folder may result in different socket paths that don't connect. ### 3. Running Tests ```bash theme={null} pnpm test ``` Runs all tests once and exits. ```bash theme={null} pnpm test --watch ``` Automatically re-runs related tests when files change. The most commonly used mode during development. ```bash theme={null} pnpm test user.model.test.ts ``` Runs only specific test files. Tests automatically connect to the Extension and display logs in real-time. ## Usage ### 1. Opening the Naite Viewer Panel Opening Naite Viewer panel in VSCode

Running 'Naite: Open Viewer' from Command Palette to open the panel

1. `Cmd+Shift+P` (macOS) or `Ctrl+Shift+P` (Windows/Linux) 2. Type "Naite: Open Viewer" 3. Enter 1. Click the Sonamu icon in VSCode's left Activity Bar 2. Select the "Naite Viewer" tab Set a keyboard shortcut for faster access: 1. `Cmd+K Cmd+S` → Keyboard Shortcuts 2. Search "Naite: Open Viewer" 3. Set desired key combination (e.g., `Cmd+Shift+N`) ### 2. Viewing Logs Logs automatically appear in Naite Viewer when tests run. #### Viewer Screen Layout Naite Viewer displays tests in a 3-level hierarchy: ```mermaid theme={null} graph TB Suite["📁 Suite Level
(UserModel)"] Test1["✓ Test Level
create user (123ms)"] Test2["✓ Test Level
update user (98ms)"] Trace1["📝 Trace Level
user:create:input"] Trace2["📝 Trace Level
user:create:output"] Trace3["📝 Trace Level
user:update:input"] Trace4["📝 Trace Level
user:update:done"] Suite --> Test1 Suite --> Test2 Test1 --> Trace1 Test1 --> Trace2 Test2 --> Trace3 Test2 --> Trace4 style Suite fill:#e3f2fd style Test1 fill:#f1f8e9 style Test2 fill:#f1f8e9 style Trace1 fill:#fff9c4 style Trace2 fill:#fff9c4 style Trace3 fill:#fff9c4 style Trace4 fill:#fff9c4 ``` ```json user:create:input theme={null} { "username": "john", "email": "john@example.com" } ``` ```json user:create:output theme={null} { "userId": 123 } ``` ```json user:update:input theme={null} { "userId": 123, "username": "jane" } ``` ```json user:update:done theme={null} { "success": true } ``` ```json user:delete:input theme={null} { "userId": 123 } ``` ```json user:delete:done theme={null} { "deleted": true } ``` ```json user:find:input theme={null} { "userId": 123 } ``` ```json user:find:output theme={null} { "user": { "id": 123, "username": "jane" } } ``` ```json user:create:input theme={null} { "username": "jane" } ``` ```json user:create:error theme={null} { "errorType": "DuplicateError", "errorMessage": "Username already exists" } ``` | Level | Description | Example | | --------- | ------------------------------ | ------------------------ | | **Suite** | Grouped by test file | `UserModel`, `PostModel` | | **Test** | Individual test case | `✓ create user (123ms)` | | **Trace** | Logs recorded with `Naite.t()` | `user:create:input` | **Status Icons**: * ✓ Pass: Test succeeded * ✗ Fail: Test failed * ⊘ Skip: Test skipped * ⌛ Pending: Waiting **Interactions**: * Click Suite/Test to expand/collapse * Click Trace to show callstack info * Click each callstack frame to navigate to code location Naite Viewer main screen

Test logs displayed in actual Naite Viewer (Suite > Test > Trace hierarchy)

**Real-time Updates**: In watch mode, when you modify a file, tests auto-rerun and the Viewer updates immediately. This lets you see the impact of code changes right away. ### 3. Checking Callstack Click on a log to see detailed information about that `Naite.t()` call. ```text theme={null} user:create:input { username: "john", email: "john@example.com" } 📍 Direct call location: /Users/.../user.model.test.ts:20 📚 Full callstack: 1. test (user.model.test.ts:20) ↑ Click to navigate to this location 2. createUser (user.model.ts:45) 3. runWithMockContext (bootstrap.ts:58) ``` **Callstack meaning**: 1. `test` (line 20): Location where `Naite.t()` was called in test code 2. `createUser` (line 45): Actual business logic called by test 3. `runWithMockContext`: Sonamu's Context wrapper (displayed up to here) Naite Viewer callstack details

Callstack information and code navigation feature when clicking on a log

Clicking each item in the callstack navigates directly to the exact line in that file. This is especially useful for debugging complex call chains. ### 4. Filtering and Search In large-scale tests, hundreds of logs can be generated. Use filtering to quickly find desired logs. Show only logs from specific modules with wildcard patterns: ```text theme={null} user:* → user:create, user:update, user:delete syncer:* → syncer:renderTemplate, syncer:writeFile *:create → user:create, post:create syncer:*:user → syncer:renderTemplate:user, syncer:writeFile:user ``` Filtering happens in real-time as you type patterns in the input field. Search by log content, file path, function name: * Key search: `user:create` * Value search: `"john"` * File search: `user.model.test.ts` * Function search: `createUser` Search results are highlighted. Filter by test status: * ✓ Passed only: Only successful tests * ✗ Failed only: Only failed tests * ⊘ Skipped: Skipped tests * ⌛ Pending: Pending tests ## Practical Use Cases ### 1. Debugging Complex Business Logic When debugging complex logic that goes through multiple steps, you can track the state at each step. ```typescript theme={null} test("full order processing flow", async () => { // Step 1: Order validation Naite.t("order:validate:start", { orderId: 123 }); await validateOrder(123); Naite.t("order:validate:done", { valid: true }); // Step 2: Inventory check Naite.t("order:inventory:check", { productId: 456 }); await checkInventory(456); Naite.t("order:inventory:available", { quantity: 10 }); // Step 3: Payment processing Naite.t("order:payment:start", { amount: 50000 }); await processPayment({ orderId: 123, amount: 50000 }); Naite.t("order:payment:done", { transactionId: "tx_789" }); // Step 4: Start shipping Naite.t("order:shipping:start", { orderId: 123 }); await startShipping(123); Naite.t("order:shipping:done", { trackingNumber: "TRK_001" }); }); ``` In the Viewer, it displays like this: ```text theme={null} ✓ full order processing flow (456ms) └─ order:validate:start { orderId: 123 } └─ order:validate:done { valid: true } └─ order:inventory:check { productId: 456 } └─ order:inventory:available { quantity: 10 } └─ order:payment:start { amount: 50000 } └─ order:payment:done { transactionId: "tx_789" } └─ order:shipping:start { orderId: 123 } └─ order:shipping:done { trackingNumber: "TRK_001" } ``` If payment step failed: * Logs only up to `order:payment:start` * Clearly identify which step succeeded * Use callstack to confirm exact failure location **Using filters**: * `order:payment:*` → Show only payment-related logs * `order:*:start` → Show only start logs for all steps ### 2. Syncer Code Generation Tracking Track which templates Sonamu's Syncer rendered and which files it created. ```typescript theme={null} test("User entity full generation", async () => { await Sonamu.syncer.generateAll({ entityId: "User" }); // Check only Syncer-related logs with syncer:* filter const syncerLogs = Naite.get("syncer:*").result(); expect(syncerLogs.length).toBeGreaterThan(0); }); ``` Viewer shows all operations performed by Syncer: ```text theme={null} ✓ User entity full generation (2.3s) └─ syncer:generateAll:start { entityId: "User" } └─ syncer:renderTemplate { template: "model", entityId: "User" } └─ syncer:writeFile { path: "user.model.ts" } └─ syncer:renderTemplate { template: "types", entityId: "User" } └─ syncer:writeFile { path: "user.types.ts" } └─ syncer:renderTemplate { template: "service", entityId: "User" } └─ syncer:writeFile { path: "user.service.ts" } └─ syncer:generateAll:done { filesCreated: 3 } ``` **Analysis**: * See order of file creation * Measure each template rendering time * Filter and check specific templates (`syncer:renderTemplate:*`) ### 3. API Call Chain Tracking When calling multiple APIs in sequence, track inputs and outputs of each API. ```typescript theme={null} test("create post → add comment → send notification", async () => { // 1. Create post Naite.t("api:post:create:request", { title: "Hello" }); const { post } = await postModel.create({ title: "Hello" }); Naite.t("api:post:create:response", { postId: post.id }); // 2. Add comment Naite.t("api:comment:create:request", { postId: post.id, content: "Nice!" }); const { comment } = await commentModel.create({ post_id: post.id, content: "Nice!" }); Naite.t("api:comment:create:response", { commentId: comment.id }); // 3. Notify author Naite.t("api:notification:send:request", { userId: post.author_id, type: "new_comment" }); await notificationService.send({ userId: post.author_id, type: "new_comment", data: { commentId: comment.id } }); Naite.t("api:notification:send:response", { sent: true }); }); ``` **request/response Pattern**: Logging `:request` and `:response` before and after API calls allows clear tracking of each API's inputs and outputs. This is especially useful in integration tests. ### 4. Identifying Performance Bottlenecks Find sections that take long and optimize them. ```typescript theme={null} test("large data processing performance", async () => { Naite.t("perf:start", { timestamp: Date.now() }); // Measure time for each step Naite.t("perf:fetch:start", { timestamp: Date.now() }); const data = await fetchLargeData(); Naite.t("perf:fetch:done", { timestamp: Date.now(), dataSize: data.length }); Naite.t("perf:process:start", { timestamp: Date.now() }); const processed = await processData(data); Naite.t("perf:process:done", { timestamp: Date.now(), processedCount: processed.length }); Naite.t("perf:save:start", { timestamp: Date.now() }); await saveToDatabase(processed); Naite.t("perf:save:done", { timestamp: Date.now() }); Naite.t("perf:end", { timestamp: Date.now() }); }); ``` Comparing timestamps for each step in Viewer: ```text theme={null} ✓ large data processing performance (5.2s) perf:start 12:34:56.000 perf:fetch:start 12:34:56.001 perf:fetch:done 12:34:57.500 ← 1.5 seconds perf:process:start 12:34:57.501 perf:process:done 12:35:00.800 ← 3.3 seconds (bottleneck!) perf:save:start 12:35:00.801 perf:save:done 12:35:01.200 ← 0.4 seconds perf:end 12:35:01.201 ``` **Analysis result**: * `processData` takes longest at 3.3 seconds (bottleneck) * `fetchLargeData` is acceptable at 1.5 seconds * `saveToDatabase` is fast at 0.4 seconds → Focus optimization on `processData` ### 5. Error Cause Tracking Track which step and what data caused an error. ```typescript theme={null} test("invalid input handling", async () => { try { Naite.t("user:create:input", { username: "" }); // Empty value await userModel.create({ username: "", email: "test@test.com" }); } catch (error) { Naite.t("user:create:error", { errorType: error.constructor.name, errorMessage: error.message, inputData: { username: "" } }); // The callstack of the error log shows exact failure location } }); ``` **Importance of Callstack for Errors**: The Viewer's callstack info shows the exact code line where the error occurred. This is especially useful for complex call chains that are hard to figure out with `console.log`. ## Understanding Internal Structure ### NaiteReporter Connection Management NaiteReporter includes buffering and reconnection logic for stable socket connection management. ```typescript theme={null} class NaiteReporterClass { private socketPath: string | null = null; private socket: Socket | null = null; private connected = false; private buffer: string[] = []; /** * Ensure socket connection * - Return immediately if already connected * - Store messages in buffer if connecting * - Ignore connection failure (Extension may be off) */ private async ensureConnection(): Promise { if (this.connected) return; return new Promise((resolve, reject) => { this.socketPath = getSocketPath(); this.socket = connect(this.socketPath); this.socket.on("connect", () => { this.connected = true; // Send buffered messages for (const msg of this.buffer) { this.socket?.write(msg); } this.buffer = []; resolve(); }); this.socket.on("error", () => { // Ignore error as Extension may be off this.connected = false; this.socket = null; reject(); }); this.socket.on("close", () => { this.connected = false; this.socket = null; }); }); } /** * Send message * - Send immediately if connected * - Store in buffer if connecting */ private async send(data: NaiteMessage): Promise { const msg = `${JSON.stringify(data)}\n`; await this.ensureConnection().catch(() => {}); if (this.connected && this.socket) { this.socket.write(msg); } else { this.buffer.push(msg); } } async startTestRun() { if (process.env.CI) return; // Ignore in CI await this.send({ type: "run/start", startedAt: new Date().toISOString(), }); } async reportTestResult(result: TestResult) { if (process.env.CI) return; await this.send({ type: "test/result", receivedAt: new Date().toISOString(), ...result, }); } async endTestRun() { if (process.env.CI) return; await this.send({ type: "run/end", endedAt: new Date().toISOString(), }); // Close socket if (this.socket) { this.socket.end(); this.socket = null; this.connected = false; } } } ``` **Key mechanisms**: 1. **Buffering**: Stores messages in buffer even if Extension isn't ready 2. **Lazy connection**: Connection failure is not treated as error 3. **Auto resend**: Sends all buffered messages on successful connection 4. **CI detection**: Skips socket communication in CI environment ### Per-Project Socket Isolation Isolate logs when working on multiple Sonamu projects simultaneously. ```typescript theme={null} import { createHash } from "crypto"; import { join } from "path"; function getProjectHash(configPath: string): string { return createHash("md5") .update(configPath) .digest("hex") .slice(0, 8); } // Example const projectA = "/Users/noa/project-a/api/src/sonamu.config.ts"; const hashA = getProjectHash(projectA); // → "a1b2c3d4" const projectB = "/Users/noa/project-b/api/src/sonamu.config.ts"; const hashB = getProjectHash(projectB); // → "e5f6g7h8" ``` ```typescript theme={null} function getSocketPath(): string { const configPath = join( findApiRootPath(), "src", "sonamu.config.ts" ); const hash = getProjectHash(configPath); return process.platform === "win32" ? `\\\\.\\pipe\\naite-${hash}` : join(homedir(), ".sonamu", `naite-${hash}.sock`); } ``` ```bash theme={null} # Project A /Users/noa/project-a/api/src/sonamu.config.ts → ~/.sonamu/naite-a1b2c3d4.sock # Project B /Users/noa/project-b/api/src/sonamu.config.ts → ~/.sonamu/naite-e5f6g7h8.sock # Each uses independent socket # Extension connects to different socket per project ``` **Benefits**: * Complete isolation of logs between projects * Simultaneous execution support (test A while testing B) * Stable operation without conflicts ### Integration with bootstrap.ts Sonamu's test bootstrap calls `Naite.getAllTraces()` for each test to collect logs. ```typescript theme={null} export const test = Object.assign( async (title: string, fn: TestFunction