@lineai/bluebeam-api/TESTING.md

Your unofficial library for Bluebeam API for human and AI developers. Provides TypeScript support, entity classes, and developer-friendly features. Perfect for AI coders, construction professionals, and document management tasks. Includes comprehensive JS

# Testing Guide

This guide explains how to run the Bluebeam API tests, including functional tests that connect to the actual Bluebeam API.

## Test Types

### Unit Tests
Basic functionality tests that don't require API credentials:
```bash
yarn test:unit
```

### Functional Tests
Integration tests that connect to the real Bluebeam API and require valid credentials.

## Setting Up Functional Tests

To run the functional tests, you need to set up OAuth 2.0 credentials with Bluebeam:

### 1. Register Your Application

1. Go to [developers.bluebeam.com](https://developers.bluebeam.com)
2. Log in with your Bluebeam account
3. Navigate to "My Apps" and create a new application
4. Set your redirect URI (e.g., `http://localhost:3000/callback`)
5. Note your `client_id` and `client_secret`

### 2. Get an Access Token

#### Option A: Authorization Code Flow (Recommended)

1. Create an authorization URL:
```javascript
import { createOAuthClient, createHttpClient } from '@lineai/bluebeam-api';

const httpClient = createHttpClient({ client_id: 'your-client-id' });
const auth = createOAuthClient({
  client_id: 'your-client-id',
  client_secret: 'your-client-secret',
  redirect_uri: 'http://localhost:3000/callback',
  scope: 'full_prime offline_access'
}, httpClient);

const authUrl = auth.createAuthorizationUrl('random-state-string');
console.log('Visit this URL:', authUrl);
```

2. Visit the URL, authorize your app, and copy the `code` from the callback
3. Exchange the code for tokens:
```javascript
const tokens = await auth.exchangeCodeForToken('your-authorization-code');
console.log('Access Token:', tokens.access_token);
```

#### Option B: Use Postman or API Client

1. Set up the authorization request in Postman
2. Follow the OAuth 2.0 flow to get an access token
3. Use the token for testing

### 3. Set Environment Variables

Create a `.env.local` file in the project root:

```bash
# Bluebeam OAuth Configuration
BLUEBEAM_CLIENT_ID=your-client-id-here
BLUEBEAM_CLIENT_SECRET=your-client-secret-here
BLUEBEAM_ACCESS_TOKEN=your-access-token-here
BLUEBEAM_REDIRECT_URI=http://localhost:3000/callback
```

**⚠️ Never commit these credentials to version control!**

### 4. Run Functional Tests

```bash
# Load environment variables and run all tests
yarn test:unit

# Run specific functional test
npx ava src/lib/functional.spec.ts --verbose

# Run auth tests
npx ava src/lib/auth.spec.ts --verbose
```

## Test Scenarios

### Basic OAuth Flow Test
```bash
npx ava src/lib/auth.spec.ts -m "*OAuth client creates valid authorization URL*"
```

### Complete Functional Test
```bash
npx ava src/lib/functional.spec.ts -m "*complete OAuth workflow*" --verbose
```

### Error Handling Test
```bash
npx ava src/lib/functional.spec.ts -m "*error handling*"
```

## Expected Test Output

When functional tests run successfully, you should see output like:

```
🔐 Testing complete Bluebeam OAuth 2.0 flow and session access...
✅ Client created with OAuth configuration
✅ Authorization URL generated: /oauth2/authorize?response_type=code&client_id=...
✅ Retrieved 5 sessions (23 total)
📁 Testing session: "Project Review Session" (ID: abc-123)
✅ Session details retrieved successfully
✅ Retrieved 3 activities for session
📄 Testing markups for file: "Floor Plan.pdf" (ID: 456)
✅ Retrieved 12 markups for file
✅ Retrieved 4 valid markup statuses
📋 Available statuses: Review:Open, Review:Closed, Approval:Pending
🎉 Functional test completed successfully!
```

## Troubleshooting

### Common Issues

1. **401 Unauthorized**
   - Check your access token is valid
   - Ensure your client_id is correct
   - Token may be expired - generate a new one

2. **403 Forbidden**
   - Check your OAuth scope includes necessary permissions
   - Verify your user account has access to the requested resources

3. **404 Not Found**
   - Verify the API endpoints are correct
   - Check if you're using the right base URLs (V1 vs V2)

4. **Tests Skip with "missing credentials"**
   - Ensure environment variables are set correctly
   - Check `.env.local` file exists and has correct format

### Debug Mode

Run tests with debug output:
```bash
DEBUG=bluebeam:* npx ava src/lib/functional.spec.ts --verbose
```

## Continuous Integration

For CI environments, set the environment variables as secrets:
- `BLUEBEAM_CLIENT_ID`
- `BLUEBEAM_CLIENT_SECRET`  
- `BLUEBEAM_ACCESS_TOKEN`

Tests will automatically skip functional tests if credentials are not available.