Sovra

Rust-based Test Decider for JavaScript using Oxc

Speed up your monorepo pipeline by only running the tests affected by your code diff.

---

Features

• TypeScript support, including path aliases
• Configurable resolver, with support for extensions, export conditions and more
• High performance because it is written in Rust using Oxc
• Easy to use with Node API

Installation

yarn add sovra

Usage

getAffected(testFiles: string[], changes: string[], resolverOptions: OxcResolverOptions, ignoreTypeImports?: boolean, requireAliases?: string[])

Returns a subset of testFiles that have changes in their import graph. This is useful in order to determine which tests to run in a large repo.

Arguments

Name	Description
testFiles	List of files to check if they were affected by changes
changes	List of change entries. Each entry is either a file path (optionally file:-prefixed) or an npm package with the npm: prefix — see Change entry formats below.
resolverOptions	Configuration on how to resolve imports, see oxc-resolver
ignoreTypeImports	When true, type-only imports import type are excluded from the import graph so changes to files that are only referenced for their types do not affect tests. Defaults to false.
requireAliases	List of function calls to treat like require() — e.g. ["jest.requireActual", "vi.importActual"]. Each entry is "name" (bare call) or "object.method" (member call). Their first string-literal argument is collected as an import path.

Change entry formats

Each entry in changes follows one of these forms:

Entry	Meaning
src/foo.ts	A file path, relative to the working directory (default if no prefix is given).
file:src/foo.ts	Same as above with an explicit prefix.
npm:lodash	An npm package. Matches imports of lodash and any deep path like lodash/fp.
npm:@scope/foo	A scoped npm package. Matches imports of @scope/foo and any subpath.
npm:@scope	Treated like a package; segment-prefix matching catches every @scope/... import.
npm:lodash/fp	A subpath entry. Matches imports of lodash/fp and below, but not lodash alone.

Matching is done against the resolver's output when the package is installed (so a TypeScript path alias mapped to a local file won't false-match an npm: entry). When the resolver can't find the module on disk — e.g. you're running sovra in CI before node_modules is installed — sovra falls back to matching the raw import specifier, so npm:lodash still flags import 'lodash' even with no install.

Empty entries ("", "npm:", "file:") panic — they're treated as caller bugs, not user-facing errors. Resolving transitive dependency changes is the integrator's responsibility — sovra only matches packages that user code imports directly.

Example

import { getAffected } from "sovra";
import { execSync } from "node:child_process";
import { glob } from "glob";

const testFiles = glob.sync("src/**/*.spec.{ts,tsx}");
const changes = execSync("git diff --name-only main", { encoding: "utf8" })
  .trim()
  .split("\n");
const resolverOptions = {
  tsconfig: {
    configFile: "tsconfig.json",
  },
};

const affected = getAffected(testFiles, changes, resolverOptions);

if (affected.errors) {
  console.error(...affected.errors);
} else {
  console.log(affected.files);
}

Test

cargo test

Limitations

Imports using variables or expressions are not supported as they can only be determined during runtime:

require(process.env.SOME_VAR + ".js"); // ❌
import(`./file.${platform}.mjs`); // ❌

License

MIT © Joel Arvidsson 2024