nextav/docs/active/library-clusters/CLUSTER_FOLDER_API_TESTS.md

Cluster Folders API - Testing Guide

API Endpoint

GET /api/clusters/[id]/folders

Test Scenarios

Test 1: Virtual Root (No Path)

Request:

GET /api/clusters/1/folders

Expected Response:

{
  "isVirtualRoot": true,
  "libraries": [
    {
      "id": 1,
      "path": "/mnt/media/library1",
      "itemCount": 245,
      "totalSize": 16434124800,
      "videoCount": 245,
      "photoCount": 0,
      "textCount": 0
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0,
  "hasMore": false
}

Success Criteria:

• ✅ Returns isVirtualRoot: true
• ✅ Lists all libraries in cluster with statistics
• ✅ Shows itemCount, totalSize, videoCount, photoCount, textCount

---

Test 2: Library Root Folder

Request:

GET /api/clusters/1/folders?path=/mnt/media/library1

Expected Response:

{
  "isVirtualRoot": false,
  "currentPath": "/mnt/media/library1",
  "libraryRoot": "/mnt/media/library1",
  "libraryId": 1,
  "items": [
    {
      "name": "Movies",
      "path": "/mnt/media/library1/Movies",
      "isDirectory": true,
      "size": 0,
      "itemCount": 45
    },
    {
      "name": "video.mp4",
      "path": "/mnt/media/library1/video.mp4",
      "isDirectory": false,
      "id": 123,
      "type": "video",
      "size": 1258291200,
      "thumbnail": "/api/videos/123/thumbnail",
      "avg_rating": 4.5,
      "star_count": 8,
      "bookmark_count": 2,
      "title": "My Video"
    }
  ],
  "total": 2,
  "limit": 50,
  "offset": 0,
  "hasMore": false
}

Success Criteria:

• ✅ Returns folder contents (directories + files)
• ✅ Directories show itemCount
• ✅ Media files include database metadata (ratings, bookmarks)
• ✅ Items sorted: folders first, then files

---

Test 3: Subfolder Navigation

Request:

GET /api/clusters/1/folders?path=/mnt/media/library1/Movies/2023

Expected Response:

{
  "isVirtualRoot": false,
  "currentPath": "/mnt/media/library1/Movies/2023",
  "libraryRoot": "/mnt/media/library1",
  "libraryId": 1,
  "items": [
    {
      "name": "January",
      "path": "/mnt/media/library1/Movies/2023/January",
      "isDirectory": true,
      "size": 0,
      "itemCount": 15
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0,
  "hasMore": false
}

Success Criteria:

• ✅ Navigates into subfolders correctly
• ✅ Maintains library context (libraryRoot, libraryId)

---

Test 4: Invalid Cluster

Request:

GET /api/clusters/99999/folders

Expected Response:

{
  "error": "Cluster not found"
}

Status Code: 404

Success Criteria:

• ✅ Returns 404 for non-existent cluster
• ✅ Error message is descriptive

---

Test 5: Path Outside Cluster

Request:

GET /api/clusters/1/folders?path=/other/path/not/in/cluster

Expected Response:

{
  "error": "Path does not belong to this cluster"
}

Status Code: 403

Success Criteria:

• ✅ Returns 403 for unauthorized paths
• ✅ Prevents access to paths outside cluster libraries

---

Test 6: Non-existent Path

Request:

GET /api/clusters/1/folders?path=/mnt/media/library1/NonExistentFolder

Expected Response:

{
  "error": "Path does not exist"
}

Status Code: 404

Success Criteria:

• ✅ Returns 404 for paths that don't exist on filesystem

---

Test 7: Pagination

Request:

GET /api/clusters/1/folders?path=/mnt/media/library1&limit=2&offset=0

Expected Response:

{
  "isVirtualRoot": false,
  "currentPath": "/mnt/media/library1",
  "items": [/* first 2 items */],
  "total": 50,
  "limit": 2,
  "offset": 0,
  "hasMore": true
}

Success Criteria:

• ✅ Returns only requested number of items
• ✅ hasMore: true when more items available
• ✅ total shows actual total count

---

Manual Testing Steps

Using curl:

1. Test Virtual Root:

curl http://localhost:3000/api/clusters/1/folders

2. Test Library Folder:

curl "http://localhost:3000/api/clusters/1/folders?path=/mnt/media/library1"

3. Test Subfolder:

curl "http://localhost:3000/api/clusters/1/folders?path=/mnt/media/library1/Movies"

4. Test Invalid Path (should get 403):

curl "http://localhost:3000/api/clusters/1/folders?path=/invalid/path"

Using Browser DevTools:

1. Open cluster page in browser
2. Open DevTools → Network tab
3. Navigate to Folders tab
4. Observe API requests and responses
5. Click folders to drill down
6. Verify responses match expected format

---

Expected Behavior Summary

Scenario	Response Type	Key Fields
No path	Virtual Root	isVirtualRoot: true, libraries[]
Valid path	Folder Contents	items[], libraryRoot, currentPath
Invalid cluster	Error	error: "Cluster not found", 404
Path outside cluster	Error	error: "Path does not belong...", 403
Non-existent path	Error	error: "Path does not exist", 404
Path is file	Error	error: "Path is not a directory", 400

---

Implementation Verification Checklist

• API endpoint created at /api/clusters/[id]/folders/route.ts
• Virtual root handler returns library list with stats
• Folder contents handler returns directories + files
• Path validation prevents access outside cluster
• Media items include database metadata (ratings, bookmarks)
• Directories show item counts
• Pagination support implemented
• Error handling (403, 404, 400, 500)
• Sorting (folders first, then files, alphabetical)
• TypeScript compilation successful
• Manual testing with real cluster data
• Frontend integration (Phase 2)

---

Phase 1 Status: ✅ COMPLETE - Backend API Ready

Next Phase: Phase 2 - ClusterFolderView Component Implementation