break-check

break-check

command line tooling to detect breaking changes before you ship them

can i use break-check?

break check is a tool for projects where

• releases must follow semantic versioning
• source code and tests are kept in separate files
• new releases are associated to git tags
• you can run tests from the command line

if that sounds like your project, read on!

break check introduces the following requirements/model for your project:

• public tests can be differentiated from private tests
  • public tests specify the public API of your project
  • public tests, if changed, may indicate that breaking changes are present
  • private tests specify your project's internals and implementation details, perhaps for documentation or coverage purposes
  • private tests, if changed, cannot indicate breaking changes
• files containing public tests can be identified by a glob pattern
• you must have a command-line command that runs only the public tests in your test suite

example

single-project repository

npx break-check 
  --testPattern="*__public.test.ts" 
  --testCommand="npm run test"

this command will check out all files matching the pattern *__public.test.ts from the last release tag that contains the string my-library, and then run npm run test

if the tests fail, break-check will exit with a non-zero status code, indicating that you have breaking changes in your project at the current commit

multi-project monorepo

npx break-check 
  --tagPattern="my-library" 
  --testPattern="./packages/my-library/__tests__/**/*__public.test.ts" 
  --testCommand="cd packages/my-library && npm run test"

this command will check out all files matching the pattern *__public.test.ts from the last release tag that contains the string my-library, and then run cd packages/my-library && npm run test

if the tests fail, break-check will exit with a non-zero status code, indicating that you have breaking changes in your project at the current commit

options

option	shorthand	required	description	example
--tagPattern	-p		String which, if found in a git tag, will be considered a release tag for your library.	--tagPattern="my-library"
--testPattern	-t	✔	Glob pattern to identify files containing public tests.	--testPattern="*__public.test.ts"
--testCommand	-c	✔	Command to run to run the public tests.	--testCommand="npm run test"
--certifyCommand	-C		Command to run to certify that breaking changes have been detected.	--certifyCommand="grep -q '"my-library": major' $(find ${DIR_PATH}/.changesets -type f) && exit 0 || exit 1"
--baseDirname	-b		Directory in which to run the tests and certify the breaking changes.	--baseDirname="."