runWithMockContext

Learn how to isolate tests and control authentication state using Mock Context.

What is runWithMockContext?

runWithMockContext is a function that provides isolated Context in Sonamu’s test environment. Sonamu uses AsyncLocalStorage to maintain independent Context per request, and the same mechanism is used in tests.

Context Components

Mock Context includes the following properties:

type Context = {
  request: FastifyRequest;
  reply: FastifyReply;
  headers: IncomingHttpHeaders;
  createSSE: <T extends ZodObject>(events: T) => ReturnType<typeof createSSEFactory<T>>;
  naiteStore: NaiteStore;  // Naite log storage
  locale: string;          // Request locale
  user: User | null;       // Authenticated user info (better-auth)
  session: Session | null; // Session info (better-auth)
  // ... ContextExtend properties
};

A simplified Mock Context is provided in tests:

{
  session: null,
  user: null,
  naiteStore: Naite.createStore(),
  locale: "",
}

Basic Usage

Regular Tests (Unauthenticated)

Sonamu’s test() function automatically runs runWithMockContext.

import { test } from "sonamu/test";
import { Sonamu } from "sonamu";
import { expect } from "vitest";

test("Context access test", async () => {
  // test() function automatically calls runWithMockContext
  // so you can access Context directly
  const context = Sonamu.getContext();

  expect(context.user).toBeNull();
  expect(context.session).toBeNull();
  expect(context.locale).toBe("");
});

Direct Usage

You can also call runWithMockContext directly:

import { runWithMockContext } from "sonamu/test";
import { Sonamu } from "sonamu";

await runWithMockContext(async () => {
  const context = Sonamu.getContext();

  // Mock Context is active within this block
  console.log(context.user); // null (unauthenticated)
  console.log(context.session); // null
});

Testing as Authenticated User

Using testAs()

Use testAs() to simulate logged-in state as a specific user:

import { testAs } from "sonamu/test";
import { Sonamu } from "sonamu";
import { expect } from "vitest";

testAs(
  { id: 1, username: "john" },  // User info
  "authenticated user test",
  async () => {
    const context = Sonamu.getContext();
    
    expect(context.user).toEqual({ id: 1, username: "john" });
  }
);

Type Safety

testAs() supports generics for type safety:

type MyUser = {
  id: number;
  username: string;
  role: "admin" | "user";
};

testAs<MyUser>(
  { id: 1, username: "admin", role: "admin" },
  "admin permission test",
  async () => {
    const context = Sonamu.getContext();
    
    // context.user is inferred as MyUser | null
    expect(context.user?.role).toBe("admin");
  }
);

Practical Examples

Model Method Test

import { test, testAs } from "sonamu/test";
import { userModel } from "../application/user/user.model";
import { expect } from "vitest";

test("user list query (unauthenticated)", async () => {
  // Mock Context is provided automatically
  const users = await userModel.findMany({});
  
  expect(Array.isArray(users)).toBe(true);
});

testAs(
  { id: 1, username: "john" },
  "my profile query (authenticated)",
  async () => {
    // context.user = { id: 1, username: "john" }
    const profile = await userModel.getMyProfile();
    
    expect(profile.username).toBe("john");
  }
);

Permission Verification Test

import { testAs } from "sonamu/test";
import { postModel } from "../application/post/post.model";
import { expect } from "vitest";

testAs(
  { id: 1, role: "admin" },
  "admin can delete any post",
  async () => {
    const result = await postModel.delete({ id: 999 });
    expect(result.success).toBe(true);
  }
);

testAs(
  { id: 2, role: "user" },
  "regular user cannot delete others' posts",
  async () => {
    await expect(
      postModel.delete({ id: 999 })
    ).rejects.toThrow("Permission denied");
  }
);

Context Property Manipulation

You can modify Context properties to test specific scenarios:

import { test } from "sonamu/test";
import { Sonamu } from "sonamu";
import { expect } from "vitest";

test("locale-specific response test", async () => {
  const context = Sonamu.getContext();

  // Modify Context property
  context.locale = "ko";

  const result = await someService.getLocalizedGreeting();
  expect(result).toBe("안녕하세요");
});

test() vs testAs() Comparison

test()
testAs()

Unauthenticated test

test("title", async () => {
  // context.user === null
});

When to use:

Testing public APIs that don’t require authentication
Testing logic regardless of authentication status
Testing Model’s basic CRUD operations

Authenticated user test

testAs(user, "title", async () => {
  // context.user === user
});

When to use:

Testing APIs that require login
Testing user-specific permissions
Testing features that require ownership verification

Internal Structure

getMockContext()

Mock Context is created as follows:

function getMockContext(): Context {
  return {
    session: null,
    user: null,
    naiteStore: Naite.createStore(),
    locale: "",
  } as unknown as Context;
}

Features:

session: Initialized as null (unauthenticated state)
user: Default is null (unauthenticated state)
naiteStore: Independent log storage per test
locale: Initialized as empty string

AsyncLocalStorage Isolation

Sonamu uses Node.js AsyncLocalStorage to isolate Context:

export async function runWithContext(
  context: Context | null, 
  fn: () => Promise<void>
) {
  await Sonamu.asyncLocalStorage.run(
    { context: context ?? getMockContext() }, 
    fn
  );
}

export async function runWithMockContext(fn: () => Promise<void>) {
  await runWithContext(getMockContext(), fn);
}

Benefits of isolation:

Context doesn’t mix between tests
Safe for parallel test execution
Each test has independent Naite log storage

How test() Wrapper Works

Sonamu’s test() function wraps Vitest’s test() to automatically provide Mock Context:

export const test = async (
  title: string, 
  fn: TestFunction<object>, 
  options?: TestOptions
) => {
  return vitestTest(title, options, async (context) => {
    await runWithMockContext(async () => {
      try {
        await fn(context);
        context.task.meta.traces = Naite.getAllTraces();
      } catch (e: unknown) {
        context.task.meta.traces = Naite.getAllTraces();
        throw e;
      }
    });
  });
};

Process:

Execute Vitest’s test()
Create and activate Mock Context with runWithMockContext()
Execute test function
Collect Naite logs regardless of success/failure
Automatic Context cleanup

testAs() Structure

testAs() receives additional user info to extend Context:

export const testAs = async <User extends AuthContext["user"]>(
  user: User,
  title: string,
  fn: TestFunction<object>,
  options?: TestOptions,
) => {
  return vitestTest(title, options, async (context) => {
    await runWithContext(
      {
        ...getMockContext(),
        user,  // Add user info
      },
      async () => {
        try {
          await fn(context);
          context.task.meta.traces = Naite.getAllTraces();
        } catch (e: unknown) {
          context.task.meta.traces = Naite.getAllTraces();
          throw e;
        }
      },
    );
  });
};

Cautions

Cautions when using Context:

Cannot access Context outside test(): Sonamu.getContext() should only be called inside test functions. Returns undefined if called outside.
Scope of Context modifications: Modifying Context affects the entire test. Automatically cleaned up when test ends.

testAs() parameter order: User info is the first parameter.

// ✅ Correct usage
testAs(user, "title", async () => {});

// ❌ Wrong usage
testAs("title", user, async () => {});

Type safety: User type for testAs() must extend AuthContext["user"].

Next Steps

Database Mocking

Isolating DB tests with transactions

API Mocking

Mocking external API calls

Naite Logging

Recording and tracking test logs

Bootstrap

Test environment initialization

Get Started

Core Concepts

Database

API Development

Frontend Integration

Testing

Advanced Features

Tools & CLI

Configuration

API Reference

Troubleshooting

FAQ

What is runWithMockContext?

Context Components

Basic Usage

Regular Tests (Unauthenticated)

Direct Usage

Testing as Authenticated User

Using testAs()

Type Safety

Practical Examples

Model Method Test

Permission Verification Test

Context Property Manipulation

test() vs testAs() Comparison

Internal Structure

getMockContext()

AsyncLocalStorage Isolation

How test() Wrapper Works

testAs() Structure

Cautions

Next Steps

Database Mocking

API Mocking

Naite Logging

Bootstrap

​What is runWithMockContext?

​Context Components

​Basic Usage

​Regular Tests (Unauthenticated)

​Direct Usage

​Testing as Authenticated User

​Using testAs()

​Type Safety

​Practical Examples

​Model Method Test

​Permission Verification Test

​Context Property Manipulation

​test() vs testAs() Comparison

​Internal Structure

​getMockContext()

​AsyncLocalStorage Isolation

​How test() Wrapper Works

​testAs() Structure

​Cautions

​Next Steps

Database Mocking

API Mocking

Naite Logging

Bootstrap

What is runWithMockContext?

Context Components

Basic Usage

Regular Tests (Unauthenticated)

Direct Usage

Testing as Authenticated User

Using testAs()

Type Safety

Practical Examples

Model Method Test

Permission Verification Test

Context Property Manipulation

test() vs testAs() Comparison

Internal Structure

getMockContext()

AsyncLocalStorage Isolation

How test() Wrapper Works

testAs() Structure

Cautions

Next Steps