app/tests

Ponderants Test Suite

This directory contains all automated and manual tests for the Ponderants application.

Directory Structure

tests/
├── magnitude/          # Magnitude.run automated tests
│   └── node-publishing.mag.ts
├── helpers/           # Reusable test utilities
│   ├── playwright-helpers.ts
│   └── README.md
└── README.md         # This file

Test Frameworks

Magnitude.run

AI-powered end-to-end testing framework that uses vision to interact with the browser like a human.

Run tests:

pnpm test
# or
npx magnitude

Test files: *.mag.ts in the magnitude/ directory

Playwright MCP

Interactive browser automation for manual testing and debugging.

Usage: Use the Playwright MCP tools with helper functions from helpers/playwright-helpers.ts

Test Coverage

Node Publishing Flow (magnitude/node-publishing.mag.ts)

Happy Path Tests:

• ✅ User can publish a node from conversation
• ✅ User can edit node draft before publishing
• ✅ User can cancel node draft without publishing

Unhappy Path Tests:

• ✅ Cannot publish node without authentication
• ✅ Cannot publish node with empty title
• ✅ Cannot publish node with empty content
• ✅ Shows error notification if publish fails
• ✅ Handles long content with truncation
• ✅ Shows warning when cache fails but publish succeeds

Integration Tests:

• ✅ Complete user journey: Login → Converse → Publish → View

Setup

1. Install Dependencies

pnpm install

2. Configure Test Environment

cp .env.test.example .env.test

Edit .env.test and add your test credentials:

TEST_BLUESKY_USERNAME=your-test-user.bsky.social
TEST_BLUESKY_PASSWORD=your-test-password

Important: Use a dedicated test account, not your personal account!

3. Start Development Server

pnpm dev

The test server must be running on http://localhost:3000 before running tests.

4. Run Tests

pnpm test

Writing New Tests

Using Magnitude

import { test } from 'magnitude-test';

test('Test description', async (agent) => {
  await agent.open('http://localhost:3000');
  await agent.act('Describe the action');
  await agent.check('Verify the result');
});

Using Helpers

import { test } from 'magnitude-test';
import { loginWithBluesky, startConversation } from '../helpers/playwright-helpers';

test('Test with helpers', async (agent) => {
  const page = agent.page;

  await loginWithBluesky(page);
  await startConversation(page, 'My test message');

  await agent.check('Expected result');
});

Best Practices

1. Test Isolation: Each test should be independent and not rely on previous tests
2. Test Data: Use dedicated test accounts and test data
3. Cleanup: Clean up any created data after tests (nodes, conversations)
4. Error Handling: Test both happy paths and error scenarios
5. Documentation: Comment complex test logic and edge cases
6. Reusability: Use helper functions for common flows
7. Readability: Use descriptive test names and clear assertions

Continuous Integration

Tests should run on every pull request:

# .github/workflows/test.yml
- name: Run tests
  run: pnpm test

Debugging Tests

View Test Execution

Magnitude.run provides visual feedback during test execution.

Interactive Testing with Playwright MCP

Use Playwright MCP tools for step-by-step debugging:

import { loginWithBluesky } from './tests/helpers/playwright-helpers';

// In MCP session
await loginWithBluesky(page, {
  username: 'test-user.bsky.social',
  password: 'test-password'
});

Check Server Logs

Monitor the dev server output for API errors:

pnpm dev
# Watch for [POST /api/nodes] logs

Known Issues

1. OAuth Rate Limiting: Repeated login tests may hit Bluesky rate limits

   • Solution: Use fewer login tests or implement session caching

2. AI Response Times: Chat tests may timeout on slow responses

   • Solution: Increase waitForAIResponse timeout

3. Cache Failures: SurrealDB cache may fail but shouldn't break tests

   • Expected: Tests should still pass with warning notifications

Resources

• Magnitude.run Documentation
• Playwright Documentation
• ATProto OAuth Spec
• Bluesky API Docs