app/tests/README.md

# 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:**
```bash
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
```bash
pnpm install
```

### 2. Configure Test Environment
```bash
cp .env.test.example .env.test
```

Edit `.env.test` and add your test credentials:
```env
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
```bash
pnpm dev
```

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

### 4. Run Tests
```bash
pnpm test
```

## Writing New Tests

### Using Magnitude
```typescript
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
```typescript
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:

```yaml
# .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:

```typescript
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:
```bash
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](https://magnitude.run/docs)
- [Playwright Documentation](https://playwright.dev)
- [ATProto OAuth Spec](https://atproto.com/specs/oauth)
- [Bluesky API Docs](https://docs.bsky.app)