Testing Guide - Directus Usage Analytics Extension

Complete guide for testing the extension in a local Docker-based Directus environment.

Prerequisites

Docker & Docker Compose installed
Node.js 18.x or higher
npm 9.x or higher

Quick Start

1. Build the Extension

# Install dependencies
npm install

# Build the extension (creates dist/ folder)
npm run build

Expected Output:

dist/api.js (~79KB) - Backend endpoint
dist/app.js (~244KB) - Frontend module

Note: The build process automatically converts @shared/constants imports to relative paths for Docker compatibility.

2. Start Directus with Docker

# Start all services (PostgreSQL + Directus)
docker-compose up -d

# Watch logs
docker-compose logs -f directus

Wait for:

directus-app  | Server started at http://0.0.0.0:8055

3. Access Directus Admin Panel

Open browser: http://localhost:8055
Login credentials:
- Email: admin@example.com
- Password: admin123

4. Find the Extension

Navigate to Settings (gear icon in sidebar)
Scroll down to find Usage Analytics in the settings menu
Click to open the analytics dashboard

Testing Checklist

✅ User Story 1: Collection Storage Analysis

Tab: Collection Storage

API Endpoint:

# Test direct API call
curl http://localhost:8055/usage-analytics/collections?limit=10

Expected Response:

{
  "collections": [
    { "collection": "directus_users", "row_count": 1, "percentage": 5.0 },
    { "collection": "directus_files", "row_count": 0, "percentage": 0.0 }
  ],
  "total_collections": 20,
  "total_rows": 100,
  "cached": false,
  "query_time_ms": 45,
  "timestamp": "2025-01-20T10:00:00.000Z"
}

✅ User Story 2: API Activity Analysis

Tab: API Activity

Generate Test Data (in Directus):

# Create some test collections and data
# Perform various operations: create items, read lists, update fields, delete items
# This will populate directus_activity table

API Endpoint:

# Test activity API
curl "http://localhost:8055/usage-analytics/activity?start_date=2025-01-01T00:00:00Z&end_date=2025-01-20T23:59:59Z&limit=10"

Expected Response:

{
  "total_requests": 150,
  "unique_users": 3,
  "unique_ips": 5,
  "date_range": {
    "start": "2025-01-01T00:00:00Z",
    "end": "2025-01-20T23:59:59Z"
  },
  "by_collection": [
    { "collection": "products", "count": 50, "percentage": 33.3 },
    { "collection": "users", "count": 30, "percentage": 20.0 }
  ],
  "by_action": [
    { "action": "read", "count": 80, "percentage": 53.3 },
    { "action": "create", "count": 40, "percentage": 26.7 }
  ],
  "cached": false,
  "query_time_ms": 120,
  "timestamp": "2025-01-20T10:00:00.000Z"
}

✅ User Story 3: IP-Based Traffic Analysis

Tab: API Activity (with IP filtering)

API Endpoints:

# Get top IPs
curl "http://localhost:8055/usage-analytics/activity/ips?start_date=2025-01-01T00:00:00Z&limit=10"

# Get activity for specific IP
curl "http://localhost:8055/usage-analytics/activity/ips/192.168.1.100?start_date=2025-01-01T00:00:00Z"

# Get time-series data
curl "http://localhost:8055/usage-analytics/activity/timeseries?start_date=2025-01-01T00:00:00Z&granularity=day"

Expected Top IPs Response:

{
  "ips": [
    { "ip": "192.168.1.100", "count": 50, "percentage": 33.3 },
    { "ip": "10.0.0.5", "count": 30, "percentage": 20.0 }
  ],
  "query_time_ms": 80,
  "timestamp": "2025-01-20T10:00:00.000Z"
}

Performance Testing

Database Indexes (Recommended)

For optimal performance with large directus_activity tables:

-- Connect to PostgreSQL
docker exec -it directus-db psql -U directus

-- Create indexes
CREATE INDEX idx_activity_timestamp_collection ON directus_activity(timestamp, collection);
CREATE INDEX idx_activity_timestamp_action ON directus_activity(timestamp, action);
CREATE INDEX idx_activity_timestamp_ip ON directus_activity(timestamp, ip);

-- Verify indexes
\di idx_activity_*

Load Testing

# Generate test activity (use Directus API or custom script)
# Perform 1000+ operations across different collections
# Then test query performance in Usage Analytics module

Performance Targets:

Collection query: <100ms for <50 collections
Activity query: <300ms for <10,000 records
IP query: <200ms for <1,000 unique IPs
Chart rendering: <500ms for all visualizations

Cross-Browser Testing

Test in the following browsers:

Chrome (latest)
Firefox (latest)
Safari (latest)
Edge (latest)

Features to verify:

Chart.js rendering
Vue component reactivity
Directus design system compatibility
Responsive layout

Troubleshooting

Extension Not Appearing

Symptom: Usage Analytics not visible in Settings menu

Solutions:

Verify build output exists:

ls -lh dist/
# Should show api.js and app.js

Check Docker volume mount:

docker exec -it directus-app ls -la /directus/extensions/
# Should show directus-extension-usage-analytics/

Restart Directus with clean cache:

docker-compose down
docker-compose up -d

Check Directus logs:

docker-compose logs directus | grep -i extension
docker-compose logs directus | grep -i error

Empty Charts/No Data

Symptom: Charts render but show "No data"

Solutions:

Verify database has data:

docker exec -it directus-db psql -U directus -c "SELECT COUNT(*) FROM directus_activity;"

Check API endpoints directly:

curl http://localhost:8055/usage-analytics/collections
curl http://localhost:8055/usage-analytics/activity

Open browser console (F12) and check for errors

Performance Issues

Symptom: Slow query times or timeouts

Solutions:

Create recommended database indexes (see above)
Reduce date range (test with 24 hours instead of 90 days)
Enable Redis caching:
- Uncomment Redis service in docker-compose.yml
- Uncomment Redis environment variables in Directus service
- Restart: docker-compose up -d

Chart Rendering Issues

Symptom: Charts not displaying or layout broken

Solutions:

Check Chart.js version in browser console:
```
Chart.version // Should be "4.x.x"
```
Verify no CSS conflicts with Directus theme
Test with different chart types (bar ↔ pie)
Check browser console for JavaScript errors

Testing with Different Databases

The extension supports PostgreSQL, MySQL, SQLite, and MSSQL.

Test with MySQL

Edit docker-compose.yml:

database:
  image: mysql:8
  environment:
    MYSQL_ROOT_PASSWORD: root
    MYSQL_DATABASE: directus
    MYSQL_USER: directus
    MYSQL_PASSWORD: directus

directus:
  environment:
    DB_CLIENT: 'mysql'
    DB_HOST: 'database'
    DB_PORT: '3306'

Test with SQLite

Edit docker-compose.yml:

directus:
  environment:
    DB_CLIENT: 'sqlite3'
    DB_FILENAME: '/directus/database/data.db'
  volumes:
    - directus-db-data:/directus/database

Clean Up

Stop and Remove Containers

docker-compose down

Remove All Data (Reset)

docker-compose down -v
# This deletes database, uploads, and Redis data

Rebuild Extension

npm run build
docker-compose restart directus

Automated Testing

Run the test suite:

# Unit tests
npm run test

# Type checking
npm run typecheck

# Linting
npm run lint

Coverage Target: ≥80% for all test types

Success Criteria

The extension is working correctly when:

✅ All 3 user stories are functional ✅ No console errors in browser ✅ API endpoints return valid JSON ✅ Charts render without issues ✅ All filters work as expected ✅ Performance meets targets (<300ms query times) ✅ Responsive design works on all screen sizes ✅ Dark/light mode both look correct ✅ Extension survives Directus restart

Next Steps

After successful testing:

Optional screenshots for README (T068)
Final quality check before npm publish (T079)
Publish to npm when ready (T080)

# Publish to npm (when ready)
npm publish --access public

Support

For issues during testing:

Check Directus logs: docker-compose logs -f directus
Check database logs: docker-compose logs -f database
Review Directus Extension Documentation
Open an issue on GitHub

Happy Testing! 🎉

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Testing Guide - Directus Usage Analytics Extension

Prerequisites

Quick Start

1. Build the Extension

2. Start Directus with Docker

3. Access Directus Admin Panel

4. Find the Extension

Testing Checklist

✅ User Story 1: Collection Storage Analysis

✅ User Story 2: API Activity Analysis

✅ User Story 3: IP-Based Traffic Analysis

Performance Testing

Database Indexes (Recommended)

Load Testing

Cross-Browser Testing

Troubleshooting

Extension Not Appearing

Empty Charts/No Data

Performance Issues

Chart Rendering Issues

Testing with Different Databases

Test with MySQL

Test with SQLite

Clean Up

Stop and Remove Containers

Remove All Data (Reset)

Rebuild Extension

Automated Testing

Success Criteria

Next Steps

Support

FilesExpand file tree

TESTING.md

Latest commit

History

TESTING.md

File metadata and controls

Testing Guide - Directus Usage Analytics Extension

Prerequisites

Quick Start

1. Build the Extension

2. Start Directus with Docker

3. Access Directus Admin Panel

4. Find the Extension

Testing Checklist

✅ User Story 1: Collection Storage Analysis

✅ User Story 2: API Activity Analysis

✅ User Story 3: IP-Based Traffic Analysis

Performance Testing

Database Indexes (Recommended)

Load Testing

Cross-Browser Testing

Troubleshooting

Extension Not Appearing

Empty Charts/No Data

Performance Issues

Chart Rendering Issues

Testing with Different Databases

Test with MySQL

Test with SQLite

Clean Up

Stop and Remove Containers

Remove All Data (Reset)

Rebuild Extension

Automated Testing

Success Criteria

Next Steps

Support