Типы возвращаемых данных

Библиотека Lighthouse предоставляет мощный инструмент для автоматизированного анализа веб-страниц, позволяя измерять производительность, доступность, SEO и другие параметры. Важной частью работы с Lighthouse является понимание типов данных, которые возвращаются при его запуске, так как правильная интерпретация результатов позволяет эффективно использовать API и интегрировать Lighthouse в автоматизированные процессы.

Объект отчета (Report Object)

При вызове Lighthouse через Node.js или через программный API, основной результат возвращается в виде объекта JavaScript. Этот объект включает в себя всю информацию об аудите страницы, включая метрики производительности, доступности, SEO, прогрессивного веб-приложения (PWA) и лучших практик.

Структура объекта отчета включает следующие ключевые поля:

  • lhr (Lighthouse Result) – основной объект с результатами аудита:

    • categories – категории аудита (performance, accessibility, best-practices, seo, pwa).
    • audits – подробные проверки с результатами, баллами и рекомендациями.
    • configSettings – настройки, применяемые при запуске аудита.
    • fetchTime – временная метка начала аудита.
    • finalUrl – URL страницы после всех редиректов.

Каждый элемент внутри audits представляет собой объект с полями:

  • id – уникальный идентификатор аудита.
  • title – краткое описание проверки.
  • description – подробное описание и рекомендации.
  • score – числовое значение оценки (от 0 до 1, либо null если недоступно).
  • numericValue – числовая метрика, например, время загрузки.
  • displayValue – текстовое представление метрики для отображения.

JSON и HTML форматы

Lighthouse может возвращать отчёт не только как объект JavaScript, но и в виде готовых файлов:

  • JSON – удобен для программной обработки и анализа в коде. Позволяет строить графики, экспортировать данные или интегрировать результаты в CI/CD.
  • HTML – визуально привлекательный отчёт с интерактивной визуализацией метрик и рекомендаций. Используется для демонстрации результатов заинтересованным сторонам.

Пример генерации JSON и HTML отчета через Node.js:

const lighthouse = require('lighthouse');
const chromeLauncher = require('chrome-launcher');

async function runLighthouse(url) {
  const chrome = await chromeLauncher.launch({chromeFlags: ['--headless']});
  const options = {output: ['json', 'html'], port: chrome.port};
  const runnerResult = await lighthouse(url, options);

  const reportJson = runnerResult.report[0]; // JSON
  const reportHtml = runnerResult.report[1]; // HTML

  await chrome.kill();
  return {reportJson, reportHtml};
}

Числовые и логические значения

Некоторые аудиты возвращают строго числовые значения (numericValue) или логические (scoreDisplayMode). Примеры:

  • numericValue – например, время до полной загрузки страницы (first-contentful-paint в миллисекундах).
  • score – оценка в диапазоне 0–1, где 1 соответствует идеальному результату.
  • scoreDisplayMode – тип отображения оценки (numeric, binary, informative).

Эти значения позволяют программно сортировать, фильтровать и сравнивать страницы по метрикам производительности или доступности.

Структура категорий

Категории (categories) содержат сводные оценки по группам аудитов. Каждая категория имеет следующие ключи:

  • id – идентификатор категории (performance, accessibility и др.).
  • title – название категории.
  • score – агрегированная оценка по всем аудитам категории.
  • auditRefs – массив ссылок на отдельные аудиты, входящие в категорию.

Пример структуры категории:

"categories": {
  "performance": {
    "id": "performance",
    "title": "Performance",
    "score": 0.92,
    "auditRefs": [
      {"id": "first-contentful-paint", "weight": 3, "group": "metrics"},
      {"id": "speed-index", "weight": 4, "group": "metrics"}
    ]
  }
}

Анализируя auditRefs и score, можно выявить узкие места и определить, какие метрики требуют оптимизации.

Массивы и вложенные объекты

Внутри аудитов могут присутствовать массивы элементов с дополнительной информацией:

  • details.items – массив конкретных проблем или элементов страницы, например, неиспользуемые CSS-правила или медиа-ресурсы.
  • details.overallSavingsMs – суммарная экономия времени после оптимизации.
  • details.headings – массив заголовков для аудита структуры страницы.

Вложенные объекты и массивы позволяют получать подробные, конкретные данные для анализа каждой метрики.

Особенности работы с Lighthouse CLI vs Node API

  • CLI возвращает результаты в формате файлов (.json, .html) или в stdout, что удобно для быстрых проверок.
  • Node API возвращает объекты JavaScript (runnerResult.lhr) для дальнейшей обработки в коде.
  • Формат JSON из CLI идентичен объекту lhr из Node API, что позволяет унифицировать обработку результатов.

Типы возвращаемых ошибок

Lighthouse возвращает ошибки в двух видах:

  1. Ошибки выполнения аудита:

    • Поле error внутри конкретного аудита с описанием причины сбоя.
    • Пример: {"id": "first-contentful-paint", "score": null, "error": "Page load failed"}

  2. Ошибки запуска:

    • Возникают на уровне Node.js или CLI (например, Chrome не запущен).
    • Исключения в виде стандартного Error объекта, содержащего message и stack.

Эта структура позволяет программно обрабатывать сбои и корректно информировать пользователя о причинах неполного отчета.

Оглавление