@xenon-device-management/xenon 2.14.0 → 2.16.0

package/scripts/dev/readme-screenshots.js

@@ -1,29 +1,51 @@
 #!/usr/bin/env node
 /**
- * Takes the README's dashboard screenshots: assets/dashboard-dark.png and
- * assets/dashboard-light.png.
+ * Takes the dashboard screenshots the README and the documentation site show.
+ *
+ *   README:  assets/dashboard-{dark,light}.png (the Devices page)
+ *   Site:    website/static/img/screens/{devices,device-control,session}-{dark,light}.webp
+ *            (the Devices page, a phone's Logs tab in device control, and a
+ *            finished session's page), 1600 px wide
  *
  * Serves the built dashboard (web/build) at /xenon/ and answers its API calls
- * with sample devices, so no server, database or phone is needed and the
- * pictures are the same on every machine.
+ * with sample data, so no server, database or phone is needed and the
+ * pictures are the same on every machine. The sample phone's screen is
+ * screenshot-fixtures/phone-screen.html: the live preview shows it, and a
+ * two-second recording made from it plays in the session's page. The sample
+ * session and log lines are in screenshot-fixtures/.
+ *
+ * The site's pictures are captured at 2x (2880 px wide) and shrunk to 1600 px
+ * WebP, which is what a 1200 px column needs and a sixth of the weight. The
+ * bundled ffmpeg has no WebP encoder, so Chromium does it: the capture is drawn
+ * to a canvas and read back as WebP (see toWebp).
  *
  *   cd web && npm run build && cd ..
  *   node scripts/dev/readme-screenshots.js
  *
- * Uses web/'s Playwright. Set CHROME_BIN to use a particular Chromium.
+ * Uses web/'s Playwright and the bundled ffmpeg (for the recording). Set
+ * CHROME_BIN to use a particular Chromium.
  */
 /* eslint-disable @typescript-eslint/no-var-requires -- a plain Node script, run without a build */
-/* global document, localStorage -- used inside the page, by Playwright */
+/* global document, Image, localStorage -- used inside the page, by Playwright */
+const { execFileSync } = require('child_process');
 const fs = require('fs');
 const http = require('http');
+const os = require('os');
 const path = require('path');
 
 const ROOT = path.resolve(__dirname, '..', '..');
 const BUILD = path.join(ROOT, 'web', 'build');
 const ASSETS = path.join(ROOT, 'assets');
+const SCREENS = path.join(ROOT, 'website', 'static', 'img', 'screens');
+const FIXTURES = path.join(__dirname, 'screenshot-fixtures');
+const SITE_IMAGE_WIDTH = 1600;
+const SITE_IMAGE_QUALITY = 0.85;
 const PORT = 5179;
+const BASE = `http://127.0.0.1:${PORT}`;
 
 const { chromium } = require(path.join(ROOT, 'web', 'node_modules', 'playwright'));
+const { logcatRecords } = require('./screenshot-fixtures/logcat');
+const sample = require('./screenshot-fixtures/session');
 
 if (!fs.existsSync(path.join(BUILD, 'index.html'))) {
   console.error('web/build is missing: run `npm run build` in web/ first.');
@@ -85,6 +107,9 @@ const DEVICES = [
     realDevice: true,
     batteryLevel: 92,
     tags: ['payments'],
+    // Device control draws the live preview at this size.
+    screenWidth: '1344',
+    screenHeight: '2992',
   },
   {
     ...base,
@@ -164,17 +189,101 @@ function answer(apiPath) {
   if (apiPath === '/devices' || apiPath.startsWith('/device')) return DEVICES;
   if (apiPath === '/queue/length') return 0;
   if (apiPath === '/queue/summary') return { total: 0, byPlatform: {}, otherCount: 0 };
-  if (apiPath === '/queue' || apiPath === '/teams' || apiPath === '/build') return [];
+  if (apiPath === '/queue' || apiPath === '/teams') return [];
+  if (apiPath === '/build') return [sample.BUILD];
   if (apiPath.startsWith('/session')) return [];
   if (apiPath.startsWith('/healing/events')) return { events: [], todayCount: 0 };
   return {};
 }
 
-async function shoot(browser, theme, file) {
+/** Calls a page made that nothing above answers: listed after each picture, to spot a missing sample. */
+const unanswered = new Set();
+
+/**
+ * Answers one /xenon/api call, or aborts it. `phone` holds the sample phone's
+ * screen as a JPEG and the session's recording as a WebM.
+ */
+async function handleApi(route, phone) {
+  const request = route.request();
+  const apiPath = new URL(request.url()).pathname.replace('/xenon/api', '');
+  const method = request.method();
+
+  // Device control, for the sample Android phone. The live preview is a still
+  // JPEG, which an <img> shows as a stream that has just loaded.
+  const control = apiPath.match(/^\/control\/([^/]+)\/(.+)$/);
+  if (control && decodeURIComponent(control[1]) === sample.UDID) {
+    const action = control[2];
+    if (action === 'stream' && method === 'GET') {
+      return route.fulfill({ contentType: 'image/jpeg', body: phone.jpeg });
+    }
+    if (action === 'stream/start') return route.fulfill({ json: { success: true, type: 'mjpeg' } });
+    if (action === 'stream/ticket')
+      return route.fulfill({ json: { ticket: 'sample', expiresIn: 60 } });
+    if (action === 'stream/leave') return route.fulfill({ json: {} });
+    if (action === 'display') return route.fulfill({ json: { state: 'on' } });
+    if (action.startsWith('stream')) return route.abort();
+  } else if (apiPath.includes('/stream')) {
+    return route.abort();
+  }
+
+  // The sample session's page.
+  const session = apiPath.match(/^\/session\/([^/]+)(?:\/(.+))?$/);
+  if (session && session[1] === sample.SESSION_ID) {
+    const part = session[2] ?? '';
+    if (part === '') return route.fulfill({ json: sample.SESSION });
+    if (part === 'session_log') return route.fulfill({ json: sample.COMMANDS });
+    if (part === 'logs/device') return route.fulfill({ json: sample.DEVICE_LOGS });
+    if (part === 'logs/debug') return route.fulfill({ json: sample.DEBUG_LOGS });
+    if (part === 'profiling') return route.fulfill({ json: [] });
+    if (part === 'metrics') return route.fulfill({ json: sample.METRICS });
+    if (part === `asset/video/${sample.VIDEO_FILE}`) {
+      return route.fulfill({ contentType: 'video/webm', body: phone.webm });
+    }
+  }
+  // No network capture for it: the page says so.
+  if (apiPath === `/interceptor/sessions/${sample.SESSION_ID}/requests`) {
+    return route.fulfill({ status: 404, json: { error: 'No capture for this session' } });
+  }
+
+  const body = answer(apiPath);
+  if (JSON.stringify(body) === '{}') unanswered.add(`${method} ${apiPath}`);
+  return route.fulfill({ json: body });
+}
+
+/**
+ * The sample phone's screen, as the live preview's JPEG and as a 2-second
+ * WebM (VP9, which the bundled ffmpeg encodes and every Chromium plays).
+ */
+async function preparePhone(browser, workDir) {
+  const page = await browser.newPage({ viewport: { width: 1344, height: 2992 } });
+  await page.setContent(fs.readFileSync(path.join(FIXTURES, 'phone-screen.html'), 'utf8'));
+  const jpeg = await page.screenshot({ type: 'jpeg', quality: 85 });
+  await page.close();
+
+  const still = path.join(workDir, 'phone.jpg');
+  const video = path.join(workDir, sample.VIDEO_FILE);
+  fs.writeFileSync(still, jpeg);
+  execFileSync(
+    require(path.join(ROOT, 'node_modules', '@ffmpeg-installer', 'ffmpeg')).path,
+    [
+      ...['-y', '-loglevel', 'error', '-loop', '1', '-framerate', '10', '-i', still, '-t', '2'],
+      ...['-vf', 'scale=448:996', '-c:v', 'libvpx-vp9', '-b:v', '0', '-crf', '40'],
+      ...['-pix_fmt', 'yuv420p', '-deadline', 'realtime', '-cpu-used', '8', video],
+    ],
+    { stdio: 'inherit' },
+  );
+  return { jpeg, webm: fs.readFileSync(video) };
+}
+
+/** A browser context in the theme, its page answering the dashboard's calls from the samples. */
+async function openPage(browser, theme, viewport, phone) {
   const context = await browser.newContext({
-    viewport: { width: 1440, height: 700 },
+    viewport,
     deviceScaleFactor: 2,
     colorScheme: theme,
+    // Log lines and sessions show local times: fix them.
+    timezoneId: 'UTC',
+    locale: 'en-US',
   });
   await context.addInitScript((t) => {
     try {
@@ -185,17 +294,15 @@ async function shoot(browser, theme, file) {
   }, theme);
   const page = await context.newPage();
   await page.route('**/socket.io/**', (route) => route.abort());
-  await page.route('**/xenon/api/**', (route) => {
-    const apiPath = new URL(route.request().url()).pathname.replace('/xenon/api', '');
-    if (apiPath.includes('/stream')) return route.abort();
-    return route.fulfill({ json: answer(apiPath) });
-  });
+  await page.route('**/xenon/api/**', (route) => handleApi(route, phone));
+  return { context, page };
+}
 
-  await page.goto(`http://127.0.0.1:${PORT}/xenon/devices`, { waitUntil: 'load' });
-  await page.waitForSelector('text=Pixel 8 Pro');
-  await page.waitForTimeout(1000);
-  // The live-updates badge says "Connecting" here only because the socket is
-  // blocked; hide it rather than picture a connection problem.
+/**
+ * The live-updates badge says "Connecting" here only because the socket is
+ * blocked; hide it rather than picture a connection problem.
+ */
+async function hideConnectingBadge(page) {
   await page.evaluate(() => {
     for (const el of document.querySelectorAll('header *')) {
       if (el.children.length === 0 && /^Connecting/.test((el.textContent || '').trim())) {
@@ -210,20 +317,166 @@ async function shoot(browser, theme, file) {
       }
     }
   });
-  await page.screenshot({ path: path.join(ASSETS, file) });
+}
+
+/** Throws if any of the texts is on the page: a picture of a spinner or an error is not a picture. */
+async function assertAbsent(page, what, texts) {
+  for (const text of texts) {
+    if ((await page.getByText(text).count()) > 0) {
+      throw new Error(`${what}: the page still says "${text}"`);
+    }
+  }
+}
+
+/** Where a picture goes. */
+function save(buffer, ...files) {
+  for (const file of files) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, buffer);
+    console.log(path.relative(ROOT, file));
+  }
+}
+
+/**
+ * A PNG as WebP, `width` px wide (its height in proportion). Chromium encodes
+ * it: the PNG is drawn to a canvas of that size and read back as WebP.
+ */
+async function toWebp(browser, png, width = SITE_IMAGE_WIDTH, quality = SITE_IMAGE_QUALITY) {
+  const page = await browser.newPage();
+  try {
+    const dataUrl = await page.evaluate(
+      async ({ base64, size, q }) => {
+        const image = new Image();
+        image.src = `data:image/png;base64,${base64}`;
+        await image.decode();
+        const canvas = document.createElement('canvas');
+        canvas.width = size;
+        canvas.height = Math.round((image.naturalHeight * size) / image.naturalWidth);
+        const context = canvas.getContext('2d');
+        context.imageSmoothingQuality = 'high';
+        context.drawImage(image, 0, 0, canvas.width, canvas.height);
+        return canvas.toDataURL('image/webp', q);
+      },
+      { base64: png.toString('base64'), size: width, q: quality },
+    );
+    if (!dataUrl.startsWith('data:image/webp;base64,')) {
+      throw new Error('this Chromium cannot encode WebP');
+    }
+    return Buffer.from(dataUrl.slice(dataUrl.indexOf(',') + 1), 'base64');
+  } finally {
+    await page.close();
+  }
+}
+
+/** The site's copy of a capture: website/static/img/screens/<name>.webp. */
+async function saveForSite(browser, png, name) {
+  save(await toWebp(browser, png), path.join(SCREENS, `${name}.webp`));
+}
+
+function reportUnanswered(what) {
+  if (unanswered.size > 0) {
+    console.log(`  ${what}: no sample for ${Array.from(unanswered).join(', ')}`);
+    unanswered.clear();
+  }
+}
+
+/** The Devices page: the README's picture and the site's. */
+async function shootDevices(browser, theme, phone) {
+  const { context, page } = await openPage(browser, theme, { width: 1440, height: 700 }, phone);
+  await page.goto(`${BASE}/xenon/devices`, { waitUntil: 'load' });
+  await page.waitForSelector('text=Pixel 8 Pro');
+  await page.waitForTimeout(1000);
+  await hideConnectingBadge(page);
+  const png = await page.screenshot();
+  save(png, path.join(ASSETS, `dashboard-${theme}.png`));
+  await saveForSite(browser, png, `devices-${theme}`);
+  reportUnanswered('devices');
+  await context.close();
+}
+
+/** Device control on the sample Android phone, the Logs tab streaming. */
+async function shootDeviceControl(browser, theme, phone) {
+  const { context, page } = await openPage(browser, theme, { width: 1440, height: 900 }, phone);
+  // The logs arrive over a WebSocket: send them once it is open, as the
+  // phone's logcat does, since the tab clears its lines when the socket opens.
+  const live = Date.UTC(2026, 9, 4, 10, 42, 30);
+  await page.routeWebSocket(/\/xenon\/api\/control\/[^/]+\/logcat/, (ws) => {
+    setTimeout(() => {
+      for (const record of logcatRecords(live)) ws.send(JSON.stringify(record));
+    }, 300);
+  });
+
+  await page.goto(`${BASE}/xenon/devices/${sample.UDID}/control/logs`, { waitUntil: 'load' });
+  await page.waitForFunction(() => {
+    const img = document.querySelector('img[alt="Device Stream"]');
+    return !!img && img.complete && img.naturalWidth > 0;
+  });
+  await page.locator('.log-status', { hasText: 'Live' }).waitFor();
+  await page.waitForFunction(() => document.querySelectorAll('.log-row').length >= 30);
+  await page.waitForTimeout(800);
+  await hideConnectingBadge(page);
+  await assertAbsent(page, 'device control', [
+    'Waiting for stream',
+    'ESTABLISHING TRACE',
+    'Stream unavailable',
+    'Display is off',
+  ]);
+  await saveForSite(
+    browser,
+    await page.screenshot({ animations: 'disabled' }),
+    `device-control-${theme}`,
+  );
+  reportUnanswered('device control');
+  await context.close();
+}
+
+/** The page of the sample session: outcome, tiles, healing, CPU and memory, recording. */
+async function shootSession(browser, theme, phone) {
+  const { context, page } = await openPage(browser, theme, { width: 1440, height: 900 }, phone);
+  await page.goto(`${BASE}/xenon/builds/${sample.BUILD_ID}/sessions/${sample.SESSION_ID}`, {
+    waitUntil: 'load',
+  });
+  await page.getByRole('heading', { name: sample.SESSION.name }).waitFor();
+  await page.waitForSelector('section[aria-label="CPU"] svg path');
+  await page.waitForFunction(() => {
+    const video = document.querySelector('video');
+    return !!video && video.readyState >= 2;
+  });
+  await page.waitForTimeout(800);
+  await hideConnectingBadge(page);
+  if (!page.url().includes(`/sessions/${sample.SESSION_ID}`)) {
+    throw new Error(`session: the page left the session (${page.url()})`);
+  }
+  await assertAbsent(page, 'session', [
+    'Loading session',
+    'Loading performance',
+    'Session not found',
+    'No video available',
+  ]);
+  await saveForSite(
+    browser,
+    await page.screenshot({ animations: 'disabled' }),
+    `session-${theme}`,
+  );
+  reportUnanswered('session');
   await context.close();
-  console.log(`assets/${file}`);
 }
 
 (async () => {
+  const workDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xenon-screenshots-'));
   await new Promise((resolve) => server.listen(PORT, '127.0.0.1', resolve));
   const browser = await chromium.launch({ executablePath: process.env.CHROME_BIN || undefined });
   try {
-    await shoot(browser, 'dark', 'dashboard-dark.png');
-    await shoot(browser, 'light', 'dashboard-light.png');
+    const phone = await preparePhone(browser, workDir);
+    for (const theme of ['dark', 'light']) {
+      await shootDevices(browser, theme, phone);
+      await shootDeviceControl(browser, theme, phone);
+      await shootSession(browser, theme, phone);
+    }
   } finally {
     await browser.close();
     server.close();
+    fs.rmSync(workDir, { recursive: true, force: true });
   }
 })().catch((err) => {
   console.error(err);

package/scripts/dev/screenshot-fixtures/logcat.js

@@ -0,0 +1,157 @@
+/**
+ * Sample log lines for the device control screenshot's Logs tab: two minutes
+ * of a made-up shop app's checkout on an Android phone. Every record has the
+ * shape the logcat WebSocket sends, `{ ts, pid, tid, level, tag, message, pkg }`.
+ *
+ * About forty lines, mostly info and debug, with the payment's two failed
+ * attempts (two errors) and what the app did about them (three warnings).
+ */
+
+const APP = 'com.example.shop';
+const SYSTEM = 'system_server';
+const APP_PID = 14233;
+const SYSTEM_PID = 1782;
+
+/** [seconds after the first line, level, tag, message] per line, oldest first. */
+const LINES = [
+  [
+    0.0,
+    'I',
+    'ActivityTaskManager',
+    'START u0 {cmp=com.example.shop/.cart.CartActivity} from uid 10312',
+  ],
+  [0.4, 'D', 'ShopCheckout', 'CartViewModel: 3 items, subtotal=145.50 USD'],
+  [1.9, 'D', 'OkHttp', '--> GET https://api.example.com/v2/cart/c_91f2/quote'],
+  [
+    2.2,
+    'D',
+    'OkHttp',
+    '<-- 200 https://api.example.com/v2/cart/c_91f2/quote (287ms, 1421-byte body)',
+  ],
+  [
+    4.8,
+    'I',
+    'ActivityTaskManager',
+    'START u0 {cmp=com.example.shop/.checkout.CheckoutActivity} from uid 10312',
+  ],
+  [5.1, 'D', 'ShopCheckout', 'CheckoutViewModel init cartId=c_91f2 items=3'],
+  [5.3, 'D', 'ShopCheckout', 'loadSavedCards() -> 2 cards'],
+  [
+    5.7,
+    'I',
+    'ActivityTaskManager',
+    'Displayed com.example.shop/.checkout.CheckoutActivity for user 0: +412ms',
+  ],
+  [
+    6.0,
+    'D',
+    'chromium',
+    '[INFO:CONSOLE(1)] "Payment sheet ready", source: https://pay.example.com/sheet.js (1)',
+  ],
+  [9.6, 'D', 'ShopCheckout', 'promo SPRING10 validated: discount=-14.55'],
+  [10.1, 'D', 'OkHttp', '--> POST https://api.example.com/v2/promo/validate (38-byte body)'],
+  [10.4, 'D', 'OkHttp', '<-- 200 https://api.example.com/v2/promo/validate (301ms, 96-byte body)'],
+  [18.5, 'I', 'ShopCheckout', 'payment method selected: card_visa_4242'],
+  [
+    24.2,
+    'D',
+    'chromium',
+    '[INFO:CONSOLE(1)] "3DS challenge not required", source: https://pay.example.com/sheet.js (1)',
+  ],
+  [41.0, 'I', 'ShopCheckout', 'Pay now tapped total=130.95 USD'],
+  [41.1, 'D', 'OkHttp', '--> POST https://api.example.com/v2/payments (412-byte body)'],
+  [43.2, 'E', 'ShopCheckout', 'payment attempt 1 of 3 failed: SocketTimeoutException: timeout'],
+  [43.3, 'W', 'ShopCheckout', 'retrying payment in 1500ms idempotencyKey=pk_7c1e'],
+  [44.8, 'D', 'OkHttp', '--> POST https://api.example.com/v2/payments (412-byte body)'],
+  [
+    46.3,
+    'E',
+    'ShopCheckout',
+    'payment attempt 2 of 3 failed: HTTP 503 (payments-gateway unavailable)',
+  ],
+  [46.4, 'W', 'ShopCheckout', 'retrying payment in 3000ms idempotencyKey=pk_7c1e'],
+  [49.5, 'D', 'OkHttp', '--> POST https://api.example.com/v2/payments (412-byte body)'],
+  [50.3, 'D', 'OkHttp', '<-- 201 https://api.example.com/v2/payments (801ms, 214-byte body)'],
+  [50.4, 'I', 'ShopCheckout', 'payment captured paymentId=pay_3f9a2c attempt=3'],
+  [
+    50.6,
+    'W',
+    'chromium',
+    '[WARNING:CONSOLE(1)] "Slow payment: 9.3s from tap to capture", source: https://pay.example.com/sheet.js (1)',
+  ],
+  [
+    50.9,
+    'I',
+    'ActivityTaskManager',
+    'START u0 {cmp=com.example.shop/.order.OrderConfirmationActivity} from uid 10312',
+  ],
+  [51.1, 'D', 'ShopCheckout', 'OrderConfirmationViewModel orderId=o_55820'],
+  [
+    51.3,
+    'I',
+    'ActivityTaskManager',
+    'Displayed com.example.shop/.order.OrderConfirmationActivity for user 0: +188ms',
+  ],
+  [51.8, 'D', 'OkHttp', '--> POST https://analytics.example.com/v1/events (233-byte body)'],
+  [52.1, 'D', 'OkHttp', '<-- 202 https://analytics.example.com/v1/events (264ms, 0-byte body)'],
+  [
+    60.4,
+    'D',
+    'chromium',
+    '[INFO:CONSOLE(1)] "Receipt rendered", source: https://pay.example.com/receipt.js (1)',
+  ],
+  [63.0, 'I', 'ShopCheckout', 'receipt email queued orderId=o_55820'],
+  [63.2, 'D', 'OkHttp', '--> POST https://api.example.com/v2/orders/o_55820/receipt (0-byte body)'],
+  [
+    63.6,
+    'D',
+    'OkHttp',
+    '<-- 202 https://api.example.com/v2/orders/o_55820/receipt (402ms, 0-byte body)',
+  ],
+  [78.9, 'D', 'ShopCheckout', 'CartRepository: cart c_91f2 cleared'],
+  [
+    91.5,
+    'I',
+    'ActivityTaskManager',
+    'Displayed com.example.shop/.home.HomeActivity for user 0: +96ms',
+  ],
+  [92.2, 'D', 'OkHttp', '--> GET https://api.example.com/v2/recommendations?limit=12'],
+  [
+    92.7,
+    'D',
+    'OkHttp',
+    '<-- 200 https://api.example.com/v2/recommendations?limit=12 (512ms, 9.8-kB body)',
+  ],
+  [
+    104.3,
+    'D',
+    'chromium',
+    '[INFO:CONSOLE(1)] "Session heartbeat", source: https://pay.example.com/sheet.js (1)',
+  ],
+  [116.8, 'D', 'ShopCheckout', 'HomeViewModel: refreshed 12 recommendations'],
+];
+
+/**
+ * The records, the last one `endTs` (epoch ms) and the first about two
+ * minutes before it. A line's thread id is its pid plus a fixed offset, so
+ * the same input gives the same records every run.
+ */
+function logcatRecords(endTs) {
+  const last = LINES[LINES.length - 1][0];
+  const start = endTs - Math.round((last + 1.2) * 1000);
+  return LINES.map(([offset, level, tag, message], i) => {
+    const fromSystem = tag === 'ActivityTaskManager';
+    const pid = fromSystem ? SYSTEM_PID : APP_PID;
+    return {
+      ts: start + Math.round(offset * 1000),
+      pid,
+      tid: fromSystem ? pid + 449 : pid + (i % 3 === 0 ? 0 : 27),
+      level,
+      tag,
+      message,
+      pkg: fromSystem ? SYSTEM : APP,
+    };
+  });
+}
+
+module.exports = { logcatRecords, LINES };