PR Cat - Testing Guide#

This guide walks you through the process of testing the GitHub integration and database functionality in PR Cat.

Prerequisites#

Before testing, make sure you have:

Set up the environment as described in the README.md
A GitHub account with access to test repositories
Ngrok installed (for webhook testing) - Download Ngrok

0. Database Initialization#

The application has been optimized to work with Edge Runtime, which means the database migrations need to be run explicitly:

Start the development server:
```
pnpm dev
```
Check the database status:
```
curl http://localhost:3000/api/status
```
If you see "migrationNeeded": true, run the migrations by visiting:
```
curl http://localhost:3000/api/migrate
```
Note: You may need to be authenticated to run migrations.
Verify the database is properly initialized:
```
curl http://localhost:3000/api/status
```
You should see "migrationNeeded": false and "version": 1

1. Testing Authentication#

Start the development server:
```
pnpm dev
```
Open http://localhost:3000 in your browser
Click "Sign In" and authorize with your GitHub account
Verify that you are redirected to the dashboard

Check the database to confirm user creation:

turso db shell prcatdb
SELECT * FROM users;

2. Testing GitHub API Integration#

2.1 User Profile#

Navigate to the dashboard (http://localhost:3000/dashboard)
Your GitHub profile information should be displayed in the sidebar

Verify API endpoint directly:

curl -H "Cookie: next-auth.session-token=YOUR_SESSION_TOKEN" http://localhost:3000/api/github/user

2.2 Organizations#

Navigate to the Teams view (http://localhost:3000/dashboard/team)
Your GitHub organizations should be listed

Verify organizations API endpoint:

curl -H "Cookie: next-auth.session-token=YOUR_SESSION_TOKEN" http://localhost:3000/api/github/organizations

Check the database:

SELECT * FROM organizations;
SELECT * FROM user_organizations;

2.3 Repositories#

Navigate to the Projects view (http://localhost:3000/dashboard/projects)
Click on an organization to view its repositories

Verify repositories API endpoint:

curl -H "Cookie: next-auth.session-token=YOUR_SESSION_TOKEN" http://localhost:3000/api/github/organizations/YOUR_ORG_NAME/repositories

Also test fetching user repositories:

curl -H "Cookie: next-auth.session-token=YOUR_SESSION_TOKEN" http://localhost:3000/api/github/repositories

Check the database:
```
SELECT * FROM repositories;
```

3. Testing Repository Tracking#

3.1 Setup Repository Tracking#

In the Projects view, find a test repository and click "Track Repository"
The application should set up a webhook and mark the repository as tracked

Verify the API directly:

curl -X POST -H "Cookie: next-auth.session-token=YOUR_SESSION_TOKEN" http://localhost:3000/api/github/repositories/REPO_ID/webhook

Check that the repository is marked as tracked in the database:
```
SELECT * FROM repositories WHERE id = REPO_ID;
```
Verify the webhook was created in GitHub:
- Go to your repository settings on GitHub
- Navigate to "Webhooks"
- Confirm a webhook pointing to your application URL exists

3.2 Testing PR Synchronization#

After tracking a repository, click "Sync Pull Requests"
The application should fetch all PRs from the repository

Test the sync API endpoint directly:

curl -X POST -H "Cookie: next-auth.session-token=YOUR_SESSION_TOKEN" http://localhost:3000/api/github/repositories/REPO_ID/sync

Check the database for pull requests:

SELECT * FROM pull_requests WHERE repository_id = REPO_ID;

4. Testing Webhooks with Ngrok#

For testing webhooks locally, you need to expose your local server to the internet.

4.1 Setting Up Ngrok#

Start your Next.js development server:
```
pnpm dev
```
In a new terminal, start ngrok on port 3000:
```
ngrok http 3000
```
Ngrok will provide a public URL (e.g., https://a1b2c3d4.ngrok.io)
Update your .env.local file with this URL:
```
APP_URL=https://a1b2c3d4.ngrok.io
```
Restart your Next.js development server

4.2 Testing Real-time Webhook Updates#

Create a new PR in your tracked GitHub repository
The webhook should trigger and add the PR to your database
Check the server logs for webhook processing events

Verify in the database:

SELECT * FROM pull_requests WHERE repository_id = REPO_ID ORDER BY created_at DESC LIMIT 1;

Update an existing PR (title, description, or status)
The webhook should trigger and update the PR data
Verify in the database that the PR was updated

5. Testing Webhook Removal#

In the Projects view, find your tracked repository and click "Untrack Repository"
The application should remove the webhook and mark the repository as not tracked

Test the API directly:

curl -X DELETE -H "Cookie: next-auth.session-token=YOUR_SESSION_TOKEN" http://localhost:3000/api/github/repositories/REPO_ID/webhook

Check the database:

SELECT * FROM repositories WHERE id = REPO_ID;

Verify the webhook was removed in GitHub:
- Go to your repository settings on GitHub
- Navigate to "Webhooks"
- Confirm the webhook was removed

6. Debugging Tips#

Viewing Database Contents#

To explore the database directly:

turso db shell prcatdb

Useful queries:

-- Check users
SELECT * FROM users;

-- Check repositories
SELECT * FROM repositories;

-- Check pull requests
SELECT * FROM pull_requests;

-- Check PR count by repository
SELECT r.name, COUNT(pr.id) as pr_count 
FROM repositories r
LEFT JOIN pull_requests pr ON r.id = pr.repository_id
GROUP BY r.name;

Troubleshooting Webhooks#

If webhooks aren't working:

Check the Turso database URL and auth token are correct (TURSO_URL and TURSO_TOKEN)
Verify the webhook URL in GitHub settings points to your Ngrok URL
Check your server logs for webhook events
Ensure the webhook secret in GitHub matches your GITHUB_WEBHOOK_SECRET env variable
Test the webhook manually using the GitHub repository settings page (Send test payload)

API Debugging#

For debugging API requests:

Use browser developer tools Network tab to monitor request/response
Check server logs for errors

Use curl with verbose flag for detailed API interactions:

curl -v -H "Cookie: next-auth.session-token=YOUR_SESSION_TOKEN" http://localhost:3000/api/status