How to Generate HTML Test Reports with Embedded Failure Screenshots in Browserbase Skills

The UI-test skill in browserbase/skills generates self-contained HTML reports by replacing placeholders in a template file with Base64-encoded screenshots, outputting a single ui-test-report.html file that requires no external assets.

The browserbase/skills repository provides a declarative UI-testing framework that produces portable, offline-ready test reports. When UI tests fail, the system captures screenshots and embeds them directly into the HTML using data URIs, creating a single artifact that can be shared with stakeholders without additional dependencies.

Understanding the HTML Report Architecture

The report generation system relies on a template-based approach documented in skills/ui-test/SKILL.md. This architecture separates the presentation layer from the test execution logic, allowing for consistent formatting across different test runs while maintaining zero external dependencies.

Phase 7 Report Generation

According to the skill documentation, Phase 7 of the UI-test workflow handles the creation of the final HTML artifact. After all sub-agents complete their assigned test groups, the main coordinating agent:

1. Aggregates test results, statuses, and log outputs from all executed steps
2. Collects screenshot data for any failed steps
3. Reads the static HTML template from skills/ui-test/references/report-template.html
4. Performs string substitution to replace template placeholders with actual test data
5. Writes the final output to .context/ui-test-report.html

This phase ensures that the report generation happens only after all test data has been collected and validated, preventing partial or corrupted reports from incomplete test runs.

The Template System

The report-template.html file contains static HTML markup with specific placeholder tokens (such as {{TEST_ROWS}}) that the skill replaces at runtime. The template includes inline CSS styling to ensure the report renders correctly without external stylesheets. When the agent processes this template, it substitutes placeholders with table rows containing test names, status badges, log excerpts, and Base64-encoded image data.

Implementing the Report Generation Workflow

To generate HTML test reports with embedded failure screenshots in your own implementation, follow the workflow used by the browserbase/skills UI-test agent.

Step 1: Capture Screenshots on Test Failure

When a test step fails, capture the browser state and convert the image data to Base64 format. This example uses Playwright, though the pattern applies to any automation library:

// During test execution
if (testStatus === 'STEP_FAIL') {
  const screenshotBuffer = await page.screenshot({ encoding: 'base64' });
  const failureData = {
    name: currentTestName,
    status: 'FAIL',
    logs: stepExecutionLogs,
    imgBase64: screenshotBuffer
  };
  testResults.push(failureData);
}

The Base64 encoding is critical because it allows the image data to be embedded directly into the HTML src attribute without requiring separate image files.

Step 2: Process the Template and Generate HTML

Read the template file, replace placeholders with your aggregated data, and write the output to the .context directory:

import { readFileSync, writeFileSync } from 'fs';
import { join } from 'path';

// Load the report template
const templatePath = join(process.cwd(), 'skills/ui-test/references/report-template.html');
const template = readFileSync(templatePath, 'utf8');

// Generate HTML rows for each test result
const testRows = testResults.map(result => {
  const statusIcon = result.status === 'PASS' ? '✅' : '❌';
  const screenshotHtml = result.imgBase64 
    ? `<img src="data:image/png;base64,${result.imgBase64}" style="max-width:400px;border:1px solid #ccc;" />`
    : '<em>No screenshot</em>';
    
  return `
<tr>
  <td>${result.name}</td>
  <td>${statusIcon} ${result.status}</td>
  <td><pre>${result.logs}</pre></td>
  <td>${screenshotHtml}</td>
</tr>`;
}).join('\n');

// Replace placeholder and write final report
const reportHtml = template.replace('{{TEST_ROWS}}', testRows);
const outputPath = join(process.cwd(), '.context/ui-test-report.html');
writeFileSync(outputPath, reportHtml);

console.log(`Report saved to ${outputPath}`);

Step 3: Open the Report Automatically

For convenience, you can automatically open the generated report in the default browser using platform-specific commands:

import { execSync } from 'child_process';
import { platform } from 'os';

const reportPath = '.context/ui-test-report.html';

if (platform() === 'darwin') {
  execSync(`open ${reportPath}`);
} else if (platform() === 'linux') {
  execSync(`xdg-open ${reportPath}`);
} else {
  execSync(`start ${reportPath}`);
}

Key Files and References

The following files in the browserbase/skills repository define and implement the HTML report generation system:

• skills/ui-test/SKILL.md – Documents Phase 7 of the UI-test workflow, detailing the exact steps for generating the HTML report and embedding screenshots as implemented in the repository.

• skills/ui-test/references/report-template.html – The static HTML template containing placeholder tokens that the skill replaces with test data and Base64-encoded images.

• skills/ui-test/README.md – Provides high-level documentation explaining the report generation feature and the .context/ui-test-report.html output location.

• skills/ui-test/EXAMPLES.md – Contains practical examples demonstrating how the report file is written and accessed after test execution.

Summary

• The browserbase/skills UI-test skill generates standalone HTML reports through Phase 7 of its execution workflow.
• Screenshots are embedded as Base64 data URIs, eliminating external file dependencies and enabling offline viewing.
• The template-based approach uses skills/ui-test/references/report-template.html with placeholder substitution to separate presentation from logic.
• Reports are output to .context/ui-test-report.html and can be opened automatically using standard OS commands.
• The implementation requires only Node.js standard library modules (fs, path, child_process), making it dependency-free and portable.

Frequently Asked Questions

Where does the UI-test skill save the generated HTML report?

The skill writes the final report to .context/ui-test-report.html within the project root directory. According to the Phase 7 documentation in skills/ui-test/SKILL.md, this location ensures the report persists in a consistent location that can be easily accessed after the test run completes.

How are screenshots embedded in the HTML report?

Screenshots are converted to Base64-encoded strings using fs.readFileSync().toString('base64') and inserted directly into img tags via data URIs (src="data:image/png;base64,..."). This technique, as described in the browserbase/skills source code, ensures all visual assets are contained within the single HTML file.

Can I customize the HTML report template?

Yes. You can modify skills/ui-test/references/report-template.html to adjust styling, add additional sections, or change the layout. Ensure you maintain the placeholder tokens (such as {{TEST_ROWS}}) that the skill expects to replace, or update the replacement logic in your report generation script accordingly.

What dependencies are required to generate the report?

The report generation system requires no external dependencies beyond Node.js core modules. The implementation uses only fs for file operations, path for cross-platform path handling, and child_process for optional automatic opening of the report. This design ensures the system works in any Node.js environment without npm packages or build steps.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}