Introduction

When you test Next.js code that touches auth, the hardest part is usually not the component logic itself. It is the session boundary: a server component, route handler, or API client expects a real user session token, but your test runner is isolated from your browser, cookies, and backend. For realtime avatar integrations, that problem gets a little more interesting because session state often gates access to a short-lived token used to initialize a live stream, a WebRTC connection, or an embedded avatar session.

This post shows a practical way to mock session tokens in Next.js tests without coupling your tests to a real auth provider. By the end, you should be able to test session-aware UI, route handlers, and avatar bootstrapping code with deterministic token values and minimal ceremony.

What we actually mean by “session token” in Next.js tests

In a Next.js app, “session token” can mean a few different things:

• A signed cookie or JWT that identifies the current user.

• A server-issued token used to authorize a downstream API call.

• A short-lived session credential returned by your backend after verifying the user.

For tests, you generally do not want to reproduce the full auth stack. You want to control the output of the session lookup layer. That layer is usually one of:

• getServerSession or similar server-side auth helpers

• A custom session parser that reads cookies or headers

• A fetch call to your own backend session endpoint

The key idea: mock the boundary, not the internals. Let your component or route handler behave as if it received a valid token, and keep the tests focused on the code you own.

Mock the session source, not the consumer

The cleanest pattern is to isolate session access behind one small module and mock that module in tests. This gives you one place to adapt when your auth implementation changes.

For example, if your app has a helper like this:

// lib/session.ts
}

// lib/session.ts
}

// lib/session.ts
}

Then your application code depends on that helper instead of reaching directly into auth state:

// app/api/avatar/route.ts

}

// app/api/avatar/route.ts

}

// app/api/avatar/route.ts

}

In a test, you mock the helper:

import { POST } from '@/app/api/avatar/route';

});

import { POST } from '@/app/api/avatar/route';

});

import { POST } from '@/app/api/avatar/route';

});

This approach works in route handlers, server actions, and server components. It also makes it easy to simulate the two important states: authenticated and unauthenticated.

Mocking cookies and headers in route-handler tests

If your code reads session state from cookies or headers directly, you can still keep tests clean by building a minimal request object. This is useful when the token is propagated as a bearer credential from the browser to your backend.

import { NextRequest } from 'next/server';

});

import { NextRequest } from 'next/server';

});

import { NextRequest } from 'next/server';

});

If your implementation depends on cookies, use a helper to populate the request headers rather than mutating globals. That keeps the test closer to the runtime behavior and avoids hidden coupling between tests.

A useful rule: if the code under test only needs to know whether a token is present and valid, do not fully verify token signatures in unit tests. That belongs in integration tests with the real auth service or a dedicated crypto test, not in every route test.

Testing token-dependent avatar bootstrapping

Realtime avatar integrations usually have a two-step flow:

1. The client authenticates to your app.

2. Your backend returns a token or session payload that allows the client to initialize the realtime avatar connection.

In a Next.js app, the client may render a chat UI while a server route fetches the avatar session. The exact transport depends on your stack, but the testing shape is the same: mock the session token provider, then assert the downstream request is made with the expected value.

import { initializeAvatar } from '@/lib/avatar';

});

import { initializeAvatar } from '@/lib/avatar';

});

import { initializeAvatar } from '@/lib/avatar';

});

If your avatar bootstrap code calls an API endpoint, assert on the request shape rather than the entire response payload. That keeps the test stable when response fields evolve. For example, you might check that the request includes an authorization header, a session ID, or a specific payload field, but not the entire nested object returned by the avatar service.

When to use integration tests instead of mocks

Mocks are ideal for deterministic unit tests, but they have limits. You should still add a smaller number of integration tests for cases where the contract matters:

• Token parsing from real cookies or headers

• Authorization failures and refresh flows

• Serialization across the client/server boundary in the App Router

• Any code that must work with streaming or WebRTC initialization timing

Realtime media is especially sensitive to timing. A mock can verify that you pass a token to the right place, but it cannot tell you whether the browser will successfully establish a peer connection or whether your session expires before the avatar stream starts. Keep those behaviors in a smaller set of end-to-end tests.

One pragmatic pattern is:

• Unit tests: mock the session token provider and validate app logic.

• Integration tests: validate auth wiring and API contracts.

• End-to-end tests: validate browser startup, media negotiation, and visible avatar behavior.

Where Protoface fits

Protoface is relevant here because realtime avatar integrations often need a session gate before the browser or voice agent can attach to an avatar stream. In practice, you will usually create or manage those sessions server-side through the REST API or the Python SDK, then hand a scoped session credential back to the client or agent runtime. That makes session mocking in Next.js directly useful: your tests can pretend the backend already issued a valid session token without involving the real API.

If you are exercising the API from server code, a minimal request shape looks like this:

curl -X POST https://api.protoface.com/<session-endpoint> \
-d '{ "avatar_id": "avatar_123" }'

curl -X POST https://api.protoface.com/<session-endpoint> \
-d '{ "avatar_id": "avatar_123" }'

curl -X POST https://api.protoface.com/<session-endpoint> \
-d '{ "avatar_id": "avatar_123" }'

The exact endpoint and fields depend on the docs, but the important part for tests is the boundary: your Next.js code should consume a session token from your own helper, not call the external API inline from every component.

If you prefer Python for session provisioning or avatar management, the same pattern applies: keep the API call behind a small service function so your frontend tests can mock the return value cleanly. See the docs for the current request and response shapes.

Practical gotchas

Three issues come up repeatedly:

• Mock leakage between tests. Reset spies and mocks after each test, especially if multiple cases reuse the same session helper.

• Mixing client and server assumptions. A token available in a browser cookie is not automatically available in a server component test. Model the runtime you are actually testing.

• Testing implementation details. Do not assert that a specific auth library was called unless that is the behavior you own and care about. Assert on the token contract your code consumes.

For a voice agent or video avatar, a good test usually answers one question: “Given a valid session token, does my app build the correct request or render the correct state?” If the answer is yes, you have isolated the expensive realtime parts behind a stable test seam.

Conclusion

Mocking session tokens in Next.js tests is mostly about discipline: put auth behind a tiny boundary, inject or mock that boundary in tests, and only reach for integration tests when you need to verify the real session flow. That keeps your tests fast, deterministic, and focused on the code you actually own.

If you are wiring up realtime avatars or voice-agent sessions, the same technique helps you test the bootstrap path without standing up a full auth stack every time. For implementation details and current API shapes, start with the documentation and the relevant example repos.