Keinsaas Navigator

To test interactions between different users (e.g., sharing an agent from User A to User B), you must manually create new browser contexts for each user within a single test.

Note: Because multi-user tests involve multiple browser instances interacting, you should set the test block to run sequentially using test.describe.configure({ mode: 'serial' }); to avoid race conditions during parallel execution.

import { TEST_USERS } from '../constants/test-users';

test.describe('Agent Sharing', () => {
  // Ensure tests in this block run one after another
  test.describe.configure({ mode: 'serial' });

  test('user sharing workflow', async ({ browser }) => {
    // User 1 setup
    const user1Context = await browser.newContext({
      storageState: TEST_USERS.editor.authFile,
    });
    const user1Page = await user1Context.newPage();

    // ... User 1 performs actions ...

    // User 2 setup
    const user2Context = await browser.newContext({
      storageState: TEST_USERS.editor2.authFile,
    });
    const user2Page = await user2Context.newPage();

    // ... User 2 interacts with shared agent ...
  });
});

The application functions as an OAuth client, managing OAuth sessions within a PostgreSQL database. The flow is triggered during server startup when MCP clients attempt to connect.

Key Lifecycle Stages:

1. Connection Attempt: The MCPClient attempts to connect. The PgOAuthClientProvider checks the OAuthRepository (DB) for an existing token session.
2. Authorization State: If no valid token session exists, the client enters an authorizing state, which triggers a prompt in the UI for user intervention.
3. User Authorization: The user clicks 'Authorize' in the UI, which calls authorizeMcpClientAction(id) on the server. The server then provides an authorizationUrl to the client.
4. OAuth Handshake: The client opens a popup to the OAuth Server for login/consent. Upon success, the server receives a callback at /api/mcp/oauth/callback?code&state.
5. Session Completion: The application retrieves the session by state, calls finishAuth(code) on the client, and the provider saves the tokens via saveTokensAndCleanup(mcpServerId, state).
6. Success: The client is refreshed, and the UI receives an MCP_OAUTH_SUCCESS postMessage.

Security and Reliability Features:

• Multi-instance Safety: Each authorization attempt uses a unique state. When tokens are successfully saved, any incomplete or stale sessions for that specific mcpServerId are automatically cleaned up.
• Security Guard: If a redirect URI mismatch occurs, the system clears all active sessions and restarts the flow to prevent unauthorized access.

To ensure tests are stable and maintainable, follow these patterns:

1. Use Stable Selectors

Avoid fragile selectors like text content or CSS paths. Always use data-testid attributes.

2. Use Robust Waiting Strategies

Don't rely on arbitrary timeouts. Use Playwright's built-in waiting mechanisms:

• page.waitForLoadState('networkidle'): Wait for network activity to settle.
• page.waitForResponse(...): Wait for a specific API call to complete.
• page.waitForURL(...): Wait for navigation to a specific URL.

3. Generate Unique Test Data

Use suffixes to prevent data collisions between parallel test runs.

// ✅ Good: Stable selector
await page.getByTestId('agent-name-input').fill('My Agent');

// ✅ Good: Waiting for API response
const responsePromise = page.waitForResponse(
  (response) => response.url().includes('/api/agent/') && response.request().method() === 'PUT'
);
await page.getByTestId('save-button').click();
await responsePromise;

// ✅ Good: Unique data
const testSuffix = Date.now().toString(36) + Math.random().toString(36).slice(2, 8);
const agentName = `Test Agent ${testSuffix}`;

To run the application directly on your host machine, follow these steps. You can choose to run a local PostgreSQL instance via Docker or use an existing one.

Option 1: Full Local Setup (with Dockerized Postgres)

1. Install dependencies: pnpm i.
2. Start PostgreSQL: pnpm docker:pg.
3. Configure the .env file with your LLM API keys and the POSTGRES_URL.
4. Build and start: pnpm build:local && pnpm start.
5. For development with hot-reloading: pnpm dev.

Option 2: Hybrid Setup (App local, DB in Docker)

Use this if you want to run the app via pnpm but keep the database isolated in Docker.

1. Start Postgres: docker compose -f docker/compose.yml up -d postgres.
2. Apply migrations: pnpm db:migrate.
3. Run the app: pnpm dev or pnpm build && pnpm start.

# Full Local Setup
pnpm i
pnpm docker:pg
pnpm build:local && pnpm start

# Hybrid Setup
docker compose -f docker/compose.yml up -d postgres
pnpm db:migrate
pnpm dev