How is this different from property based testing?

Tools such as fast-check ask you to write the properties and generators yourself. breakhound ships the properties, a fixed set of invariants that hold for most libraries, and derives the generators from the type signatures, so it works on code you have never read. When it finds something, it hands you a regular Vitest test you can keep.

Is it safe to run on any package?

breakhound executes the code it scans, so treat it like running the package's own test suite. Installs use --ignore-scripts and every call runs in a child process with a timeout, which is isolation for robustness, not a security sandbox. Scan untrusted packages inside a container or a disposable VM.

Does it work with plain JavaScript without types?

It works best with TypeScript declarations, either bundled .d.ts files or DefinitelyTyped. Without types it falls back to a smaller set of generic inputs.

Will it report false positives?

Some invariants, such as time zone dependence, can be intentional for a given function. Every finding has a confidence level and a minimal reproduction so you can judge it in seconds, and --rules, --only and --exclude let you narrow the hunt.

Are runs reproducible?

Yes. Inputs come from a seeded generator (seed 42 by default, change it with --seed), the call budget is fixed with --max-calls, and each run is saved to .breakhound/last-run.jsonl and .breakhound/report.json unless you pass --no-save.

Zero config bug finder for JavaScript and TypeScript

Find bugs in any JavaScript library automatically

Point breakhound at an npm package or a local folder. It reads the TypeScript types, throws nasty edge cases at every exported function, runs each call in an isolated process under several time zones, and hands you a minimal reproduction plus a ready Vitest test for every bug. No tests to write first.

Terminal

npx breakhound ./my-lib

Terminal

pnpm dlx breakhound ./my-lib

Terminal

yarn dlx breakhound ./my-lib

Terminal

bunx breakhound ./my-lib

Get started View on GitHub

Born from 130 merged bug fixes atGoogleMicrosoftGitHubVue

Sniff, the breakhound bloodhound detective, holding a magnifying glass

~/my-lib $ npx breakhound ./my-lib

breakhound v0.1.0 my-lib@1.0.0 (local)

✓ Reading types 23 functions, 1 skipped

✓ Generating inputs edgegoat edge cases

✓ Running calls 4444 calls, 6 time zones

✓ Checking oracles 8 rules, seed 42

HIGH [lone-surrogate-output] truncate

truncate('\u{1F600}', 1) -> '\ud83d'

HIGH [timezone-dependent] yearLabel

TZ=UTC yearLabel(0) -> '1970'

TZ=America/New_York yearLabel(0) -> '1969'

HIGH [unexpected-crash] initials

initials('') -> throws TypeError

MED [nan-leak] average

average([0]) -> NaN

MED [negative-zero-sign] formatFixed

formatFixed(-0.5) -> '0.50'

Summary: 5 high, 5 medium, 0 low, 2 info

Report saved to .breakhound/report.json

Eight oracles

The bugs it sniffs out

Each oracle is an invariant that almost every library should keep. breakhound checks all eight on every exported function, with no configuration.

Split emoji

lone-surrogate-output

A string result contains half of a surrogate pair, so an emoji or astral character is cut in two.

truncate('\u{1F600}', 1) -> '\ud83d'

Time zone dependence

timezone-dependent

The same call returns different results when only the host TZ changes.

TZ=UTC yearLabel(0) -> '1970' TZ=New_York yearLabel(0) -> '1969'

Crash on valid input

unexpected-crash

A value the types allow, like an empty string, throws a TypeError.

initials('') -> throws TypeError

NaN leak

nan-leak

Finite numbers go in, NaN comes out where a real number was expected.

average([0]) -> NaN

Broken roundtrip

roundtrip

Partners such as encodeX and decodeX do not give the input back.

decodeBase(encodeBase('_')) -> ' '

Not idempotent

not-idempotent

Normalizing twice gives a different result than normalizing once.

slugify('x y') -> 'x_y' slugify(slugify('x y')) -> 'x-y'

Lost minus sign

negative-zero-sign

Values between -1 and 0 are formatted as if they were positive.

formatFixed(-0.5) -> '0.50'

Nondeterminism

nondeterministic

Same call, same input, different result, from hidden state or clocks.

label('a') -> 'a' label('a') -> 'A'

How it works

From package name to failing test in four steps

Everything below happens inside one command. You keep only the part you care about: the tests.

Read the types
breakhound installs the package with --ignore-scripts or opens your folder, then reads its TypeScript declarations to learn every exported function and parameter.
Generate inputs
Each parameter gets values from edgegoat: DST transitions, dates before 1970, emoji, lone surrogates, -0, NaN. Callbacks are generated too.
Run in isolation
Calls run in a child process with a timeout, repeated under several TZ values, with a fixed seed so every run is reproducible.
Check and report
Eight oracles judge the results. Each finding comes with a severity, a minimal reproduction and a Vitest test.

Real output

Every finding is a test you can keep

This is real --plain output from the buggy fixture in the breakhound repository. The reproduction runs on its own, and the Vitest test fails until the bug is fixed.

Terminal output

[negative-zero-sign] formatFixed drops the minus sign of numbers between -1 and 0 (confidence medium)
  formatFixed(-0.5)  -> '0.50'
  formatFixed(0.5)  -> '0.50'
  formatFixed(-1.5)  -> '-1.50'

Reproduction repro.js

repro.js

// formatFixed drops the minus sign of numbers between -1 and 0
// Found by breakhound. Package: buggy-lib@1.0.0
import { formatFixed } from 'buggy-lib';

console.log(formatFixed(-0.5));
console.log(formatFixed(0.5));
console.log(formatFixed(-1.5));

Generated test Vitest

formatFixed.test.ts

import { expect, test } from 'vitest';
import { formatFixed } from 'buggy-lib';

test("formatFixed keeps the sign of -0.5", () => {
  expect(formatFixed(-0.5)).not.toBe(formatFixed(0.5));
});

Reproduction repro.js

repro.js

// yearLabel returns different results in different time zones
// Found by breakhound. Package: buggy-lib@1.0.0
import { yearLabel } from 'buggy-lib';

for (const tz of ['UTC', 'America/Sao_Paulo']) {
  process.env.TZ = tz;
  console.log(tz, yearLabel(0));
}

Generated test Vitest

yearLabel.test.ts

import { expect, test } from 'vitest';
import { yearLabel } from 'buggy-lib';

test("yearLabel does not depend on the host time zone", () => {
  const original = process.env.TZ;
  try {
    process.env.TZ = 'UTC';
    const expected = yearLabel(0);
    process.env.TZ = 'America/Sao_Paulo';
    expect(yearLabel(0)).toEqual(expected);
  } finally {
    if (original === undefined) delete process.env.TZ;
    else process.env.TZ = original;
  }
});

Output modes: the rich TTY view by default, --plain for logs, --json or --output report.json for tools, --log run.jsonl for a JSON Lines run log and --verbose for debug lines.

Continuous integration

Gate pull requests on real bugs

Add one step to GitHub Actions. --fail-on high fails the job on serious findings, and breakhound writes annotations and a job summary on its own when it runs inside Actions. Read the CI guide.

.github/workflows/breakhound.yml

name: breakhound
on: [push, pull_request]

jobs:
  sniff:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci --ignore-scripts
      # annotations and a job summary are written automatically
      - run: npx breakhound . --fail-on high

breakhound report for my-lib@1.0.0

Severity	Findings
HIGH	5
MEDIUM	5
info	2

ERRORlone-surrogate-output truncate returns a string with a lone surrogate
truncate('\u{1F600}', 1) -> '\ud83d'

ERRORtimezone-dependent yearLabel returns different results in different time zones

WARNINGnegative-zero-sign formatFixed drops the minus sign of numbers between -1 and 0

Comparison

Where breakhound fits

breakhound complements these tools rather than replacing them. A good workflow: a free sweep with breakhound first, important properties in fast-check, parsers in Jazzer.js.

Aspect	breakhound	Tests by hand	fast-check	Jazzer.js
Approach	Type driven invariant checks	Examples you think of	Property based testing library	Coverage guided fuzzing
You write	Nothing	Every case and assertion	Properties and arbitraries	Fuzz targets
Input source	Types plus edgegoat edge cases	Your imagination	Your arbitraries, with shrinking	Mutation guided by coverage
Best at	Unicode, time zone and number formatting bugs in public APIs	Documenting intended behavior	Precise properties of your own code	Crashes and security issues in parsers
Works on code you never read	Yes	No	No	Partly, after writing a target
Output	Reproduction plus ready Vitest test	Pass or fail	Failing counterexample	Crashing input

Proof

Born from real bug fixes

breakhound is built by Alexandre Kohler, who has landed 130 merged bug fixes in projects at Google, Microsoft, GitHub, Vue and more. The oracles come straight from that work.

Mergedgithub/relative-time-element#384

The year check used UTC instead of the display time zone.

timezone-dependent Mergedgoogle/budoux#1411

Surrogate pairs were split when breaking text.

lone-surrogate-output Mergedmicrosoft/vscode-js-debug#2423

Surrogate pairs were split in debugger output.

lone-surrogate-output Mergedmozilla/pdf.js#22017

Negative numbers above -1 lost their minus sign.

negative-zero-sign Mergedvuejs/core#15618

Vue 2.7 components compiled from script setup crashed in the Vue 3 compat build.

vuejs/core

130

merged bug fixes across open source projects, each one a pattern breakhound now checks for.

FAQ

Questions

Run npx breakhound with a package name or a path. breakhound reads the TypeScript types to learn what each exported function accepts, feeds it edge case inputs, and reports calls that break invariants such as roundtrips, idempotence, sign preservation or time zone independence. You do not need to write any test first.

Let Sniff hunt your library

One command, no config, no tests to write. You get the bugs, the reproductions and the Vitest tests.

Run npx breakhound ./my-lib Read the guides

Find bugs in any JavaScript library automatically

The bugs it sniffs out

Split emoji

Time zone dependence

Crash on valid input

NaN leak

Broken roundtrip

Not idempotent

Lost minus sign

Nondeterminism

From package name to failing test in four steps

Read the types

Generate inputs

Run in isolation

Check and report

Every finding is a test you can keep

Gate pull requests on real bugs

Where breakhound fits

Born from real bug fixes

Questions

How do I find bugs automatically in a JavaScript library?

How is this different from property based testing?

Is it safe to run on any package?

Does it work with plain JavaScript without types?

Will it report false positives?

Are runs reproducible?

Let Sniff hunt your library