@snagtag/core

Framework-agnostic core utilities for SnagTag - the drop-in testing and QA plugin.

Install

npm install @snagtag/core

What's included

• Types - TestReport, CapturedElement, SnagTagAdapter, and all related interfaces
• Element capture - captureElement() takes a DOM element and returns a rich snapshot (component name, file path, CSS, form state, diagnostics)
• Diagnostics - Console error and network error listeners with 30-second rolling buffers
• Screenshot - captureScreenshot() using html-to-image (hides testing UI, scrolls to element, adds highlight ring)
• Markdown export - generateMarkdown() produces structured reports sorted by severity
• Constants - Status/severity/type labels, colour maps, display helpers

Usage

import { captureElement, generateMarkdown, installConsoleErrorListener } from '@snagtag/core'
import type { SnagTagAdapter, TestReport, CapturedElement } from '@snagtag/core'

// Capture a DOM element
const element = captureElement(document.querySelector('.my-button')!, window.location.pathname)
// Returns: { component_name, file_path, css_snapshot, diagnostics, ... }

// Generate markdown from reports
const markdown = generateMarkdown({ reports, groups: [] })

// Listen for console errors
const cleanup = installConsoleErrorListener()

Adapter interface

All storage backends implement SnagTagAdapter:

interface SnagTagAdapter {
  listReports(opts?: ListOpts): Promise<TestReport[]>
  createReport(input: TestReportInsert): Promise<TestReport>
  updateReport(id: string, patch: TestReportUpdate): Promise<TestReport>
  removeReport(id: string): Promise<void>
  countUnresolved(): Promise<number>
  findSimilar(id: string): Promise<TestReport[]>
  markFixed(ids: string[], commitRef: string | null, notes: string | null): Promise<void>
  reopen(ids: string[]): Promise<void>
  uploadScreenshot(reportId: string, blob: Blob): Promise<{ path: string; sizeBytes: number }>
  getScreenshotUrl(path: string): Promise<string>
  deleteScreenshot(path: string): Promise<void>
  listGroups(): Promise<TestReportGroup[]>
  createGroup(input: GroupInsert): Promise<TestReportGroup>
  assignReportsToGroup(groupId: string, reportIds: string[]): Promise<void>
  getActiveSession(): Promise<TestingSession | null>
  startSession(title: string): Promise<TestingSession>
  endSession(id: string): Promise<void>
  onReportChange?(callback: () => void): () => void
}

License

MIT