Core Package

Detection engine with DBSCAN clustering and pattern extraction

Overview

The core package (@flakiness-detective/core) contains the main detection algorithms:

DBSCAN clustering with cosine/euclidean distance
Rich Playwright error parsing
Pattern extraction and frequency analysis
Deterministic cluster IDs
Input validation and type safety

Installation

pnpm add @flakiness-detective/core

Basic Usage

import { FlakinessDetective } from '@flakiness-detective/core';

const detective = new FlakinessDetective(
  dataAdapter,
  embeddingProvider,
  {
    timeWindow: { days: 7 },
    clustering: {
      epsilon: 0.15,
      minPoints: 2,
      minClusterSize: 2,
      distance: 'cosine',
      maxClusters: 5
    }
  },
  'info' // log level
);

const clusters = await detective.detect();

Configuration

Time Window

timeWindow: {
  days: 7  // Analyze failures from last 7 days
}

Clustering Options

epsilon (default: 0.15)

Distance threshold for clustering. Lower values create tighter, more specific clusters.

minPoints (default: 2)

Minimum neighbors required for a core point in DBSCAN.

minClusterSize (default: 2)

Minimum failures required to form a cluster.

distance (default: 'cosine')

Distance metric: cosine or euclidean. Cosine is better for semantic embeddings.

maxClusters (default: 5)

Maximum number of clusters to return (top N by size).

Pattern Extraction

The core package automatically extracts patterns from Playwright errors:

Locators: CSS selectors, role-based locators
Matchers: toBeVisible, toContainText, etc.
Values: Actual vs expected values
Timeouts: Timeout durations
Line numbers: Source code locations
Run IDs: GitHub Actions run identifiers

TypeScript Types

import type { 
  FlakinessDetectiveConfig,
  TestFailure,
  FailureCluster 
} from '@flakiness-detective/core';