11 KiB

Raw Blame History

Localhost Testing Guide

Author: Matthew Raymer
Version: 1.0.0
Status: Testing Setup

Overview

This guide explains how to test the daily notification plugin's prefetch functionality with a localhost development API server running on your host machine.

Android Emulator Localhost Access

On Android emulator, localhost (127.0.0.1) refers to the emulator itself, not your host machine. To access your host machine's localhost from the Android emulator, use:

10.0.2.2 - Special alias that maps to host machine's localhost

Platform-Specific Localhost Addresses

Android Emulator: http://10.0.2.2:PORT
iOS Simulator: http://localhost:PORT or http://127.0.0.1:PORT
Web Browser: http://localhost:PORT

Setup Steps

1. Start Your Local Development Server

You have two options:

Option A: Use the Test API Server (Recommended for Quick Testing)

The plugin includes a ready-to-use test API server with automatic project seeding:

cd /home/matthew/projects/timesafari/daily-notification-plugin
node scripts/test-api-server-with-seed.js [port]
# Default port: 3000
# Starts on http://localhost:3000

This server:

✅ Automatically creates plans in-memory on startup (no fetch errors)
✅ Implements the /api/v2/report/plansLastUpdatedBetween endpoint
✅ Returns seeded projects when queried by planIds
✅ Ready to use immediately with auto-generated valid URI format IDs
✅ Provides debugging endpoints to view seeded projects

Note: Plans are stored in-memory only. When the server restarts, plans are re-seeded automatically.

Option B: Use Your Existing TimeSafari API Server

If you have your own localhost API server, you must create plans first. Plans are created by importing JWT claims containing a PlanAction:

Route: POST /api/v2/claim

{
  "jwtEncoded": "<signed JWT with PlanAction claim>"
}

Requirements:

JWT must contain @type: "PlanAction" in the claim payload
JWT must be signed with a valid DID key
Response includes handleId and planId if creation succeeds

Methods to Create Plans:

TimeSafari App UI (easiest) - Create projects through the app UI and note handleId from API responses
Import PlanAction JWT - Generate a signed JWT with PlanAction claim and POST to /api/v2/claim
Direct Database - Insert plans directly into your database (not recommended for production data integrity)

Note: Creating PlanAction JWTs requires DID signing and proper claim structure, which is complex. For quick testing, Option A (test API server) is recommended.

Then verify your setup:

# Seed projects to your existing API server
node scripts/seed-test-projects.js seed http://localhost:3000

# Or export projects as JSON for manual import
node scripts/seed-test-projects.js export test-projects.json

Then ensure your server implements the endpoint as described in the "Localhost API Server Requirements" section below.

2. Configure Test App for Localhost

Edit test-apps/daily-notification-test/src/config/test-user-zero.ts:

api: {
  serverMode: "localhost", // Change from "mock" to "localhost"
  servers: {
    localhost: {
      android: "http://10.0.2.2:3000", // Match your local server port
      ios: "http://localhost:3000",
      web: "http://localhost:3000"
    },
    // ... other server configs
  },
  // ...
},
testing: {
  enableMockResponses: false, // Disable mocks to use real localhost API
  // ...
}

3. Update Starred Plans in Test App

In the test app UI (UserZeroView), use updateStarredPlans() to set which project IDs to query:

// In UserZeroView.vue or your test code
await DailyNotification.updateStarredPlans({
  planIds: ["test_project_1", "test_project_2", "test_project_3"]
});

4. Schedule Notification for Testing

Schedule a notification that will trigger prefetch 5 minutes before:

await DailyNotification.scheduleDailyNotification({
  time: "11:25", // Current time + 5+ minutes for testing
  title: "Test Notification",
  body: "Testing prefetch with localhost",
  priority: "high"
});

The prefetch will run 5 minutes before (11:20 in this example) and query your localhost API.

Testing Prefetch Flow

Expected Timeline

T-0: You schedule notification for 11:25
T+0: Plugin schedules prefetch for 11:20 (5 minutes before)

T+0: Plugin logs:

DN|SCHEDULE_FETCH_START time=...
DN|WORK_ENQUEUED work_id=... fetch_at=... delay_ms=...

T+~5 minutes: WorkManager triggers prefetch at 11:20
T+~5 minutes: Plugin queries http://10.0.2.2:3000/api/v2/report/plansLastUpdatedBetween
T+~10 minutes: Notification displays at 11:25

Monitoring Prefetch

Watch logs for prefetch execution:

# Filter for prefetch-related logs
adb logcat | grep -E "DN|SCHEDULE_FETCH|FETCH_PROJECT|WORK_ENQUEUED"

# Watch WorkManager queue
adb shell dumpsys jobscheduler | grep daily_notification

# Monitor network requests (if your server logs them)
# Check your localhost server logs for POST requests to /api/v2/report/plansLastUpdatedBetween

Localhost API Server Requirements

Your localhost API server must implement:

Endpoint: `POST /api/v2/report/plansLastUpdatedBetween`

Request:

{
  "planIds": ["test_project_1", "test_project_2"],
  "afterId": "optional_jwt_id_for_pagination"
}

Response:

{
  "data": [
    {
      "planSummary": {
        "jwtId": "jwt_id_1",
        "handleId": "test_project_1",
        "name": "Test Project 1",
        "description": "Project description",
        "issuerDid": "did:key:...",
        "agentDid": "did:key:...",
        "startTime": "2025-01-01T00:00:00Z",
        "endTime": "2025-01-31T23:59:59Z"
      },
      "previousClaim": {
        "jwtId": "previous_jwt_id",
        "claimType": "project_update"
      }
    }
  ],
  "hitLimit": false,
  "pagination": {
    "hasMore": false,
    "nextAfterId": null
  }
}

Headers Required:

Authorization: Bearer <JWT_TOKEN>
Content-Type: application/json
User-Agent: TimeSafari-DailyNotificationPlugin/1.0.0

Seeding Test Projects

Using the Test API Server (Automatic)

If you're using test-api-server-with-seed.js, projects are automatically created on startup - no additional seeding needed. The server creates plans in-memory, so they're available immediately when the prefetch endpoint is called.

Using Your Real TimeSafari API Server

If your localhost API has no projects, create them via POST /api/v2/claim with a PlanAction JWT (see "Option B" section above).

Note: The seed-test-projects.js script cannot directly create plans because it would require generating signed PlanAction JWTs with DID keys, which is complex. The seed script is designed for the test API server (Option A) or for verifying API responses after plans are created through other means.

Generate Test Projects

# Generate test projects and display as JSON
node scripts/seed-test-projects.js generate

# Export projects to JSON file
node scripts/seed-test-projects.js export test-projects.json

# Seed projects directly to your API server
node scripts/seed-test-projects.js seed http://localhost:3000

# Use custom project IDs
node scripts/seed-test-projects.js seed http://localhost:3000 "project_1,project_2,project_3"

The seed script generates test projects matching the structure expected by the plugin, including:

handleId (from your config)
jwtId (timestamp-based for pagination)
planSummary (name, description, dates, location)
previousClaim (for change detection)

Using the Test API Server (Includes Seeding)

The easiest way is to use the included test API server:

node scripts/test-api-server-with-seed.js

This server:

Seeds 5 test projects automatically on startup
Provides the prefetch endpoint ready to use
Includes debugging endpoints

Quick Test Script (Alternative)

If you want to create your own minimal localhost API server:

// test-api-server.js
const express = require('express');
const app = express();

app.use(express.json());

app.post('/api/v2/report/plansLastUpdatedBetween', (req, res) => {
  console.log('📥 Prefetch request received:', {
    planIds: req.body.planIds,
    afterId: req.body.afterId,
    headers: req.headers
  });

  // Return mock response
  res.json({
    data: [
      {
        planSummary: {
          jwtId: `${Date.now()}_test_123`,
          handleId: req.body.planIds[0] || "test_project",
          name: "Localhost Test Project",
          description: "Testing prefetch from localhost",
          issuerDid: "did:test:issuer",
          agentDid: "did:test:agent",
          startTime: new Date().toISOString(),
          endTime: new Date(Date.now() + 86400000).toISOString()
        },
        previousClaim: {
          jwtId: "previous_test_jwt",
          claimType: "project_update"
        }
      }
    ],
    hitLimit: false,
    pagination: {
      hasMore: false,
      nextAfterId: null
    }
  });
});

app.listen(3000, () => {
  console.log('🧪 Test API server running on http://localhost:3000');
  console.log('📡 Android emulator should use: http://10.0.2.2:3000');
});

Run with:

node test-api-server.js

Note: The included scripts/test-api-server-with-seed.js provides the same functionality plus automatic seeding, so you may prefer to use that instead.

Troubleshooting

Prefetch Not Executing

Check WorkManager queue:

adb shell dumpsys jobscheduler | grep -A 20 "daily_notification"

Verify prefetch was scheduled:
```
adb logcat | grep "DN|SCHEDULE_FETCH"
```
Check if WorkManager has constraints:
- Battery optimization might be blocking execution
- Network might not be available
- Device might be in deep sleep

Cannot Connect to Localhost

Android Emulator: Use 10.0.2.2 not localhost or 127.0.0.1
Firewall: Check if your firewall is blocking port 3000
Server not running: Verify server is listening on correct port
Wrong port: Match the port in config with your server's port

Network Timeout

Increase timeout in config:

testing: {
  timeoutMs: 60000, // Increase from 30000 to 60000
}

Authentication Errors

Your localhost server should accept the JWT token generated by the plugin. For testing, you can:

Disable JWT validation in your localhost server
Use a test JWT secret that matches plugin config
Log the JWT in your server to see what's being sent

Switching Between Mock and Localhost

You can switch modes without rebuilding:

Mock Mode (offline testing):

api.serverMode = "mock";
testing.enableMockResponses = true;

Localhost Mode (real API calls to localhost):

api.serverMode = "localhost";
testing.enableMockResponses = false;

Staging Mode (real API calls to staging):

api.serverMode = "staging";
testing.enableMockResponses = false;

Next Steps

Test prefetch execution with real localhost API
Monitor network traffic to verify requests
Test with different starred plan IDs
Verify prefetch timing (5 minutes before notification)
Test notification delivery after prefetch completes

11 KiB Raw Blame History