refactor: fuzzer mode is unified

Author: oetr

packages/core/cli.ts

@@ -17,8 +17,13 @@
 
 import yargs, { Argv } from "yargs";
 
+import {
+	defaultCLIOptions,
+	OptionsManager,
+	OptionSource,
+} from "@jazzer.js/options";
+
 import { FuzzingExitCode, startFuzzing } from "./core";
-import { defaultCLIOptions, OptionsManager, OptionSource } from "./options";
 import { prepareArgs } from "./utils";
 
 // Use yargs to parse command line arguments and provide a nice CLI experience.

packages/core/core.ts

@@ -32,6 +32,7 @@ import {
 	registerEsmLoaderHooks,
 	registerInstrumentor,
 } from "@jazzer.js/instrumentor";
+import { OptionsManager, resolveEngine } from "@jazzer.js/options";
 
 import { getCallbacks } from "./callback";
 import {
@@ -508,14 +509,6 @@ export function asFindingAwareFuzzFn(
 // Export public API from within core module for easy access.
 export * from "./api";
 export { FuzzedDataProvider } from "./FuzzedDataProvider";
-export {
-	AllowedFuzzTestOptions,
-	Options,
-	OptionsManager,
-	OptionSource,
-	OptionsWithSource,
-	printOptions,
-} from "./options";
 
 export type {
 	FuzzTarget,

packages/core/options.ts

@@ -15,21 +15,19 @@
  */
 
 import fs from "fs";
-import * as util from "util";
 
 import * as tmp from "tmp";
 
 import {
 	type LibAflOptions,
+	Mode,
 	type OptionsManager,
+	printOptions,
 	resolveEngine,
-	toOptionsWithPrintableSources,
 } from "@jazzer.js/options";
 
 import { useDictionaryByParams } from "./dictionary";
 
-export * from "@jazzer.js/options";
-
 export function buildLibFuzzerOptions(options: OptionsManager) {
 	let params: string[] = [];
 	params = optionDependentParams(options, params);
@@ -105,7 +103,7 @@ export function buildLibAflOptions(options: OptionsManager): LibAflOptions {
 		);
 	}
 
-	if (options.get("mode") === "regression") {
+	if (options.get("mode") === Mode.Regression) {
 		// Regression mode should replay every available corpus input unless the
 		// user asked to stop for some other reason, mirroring libFuzzer's behavior.
 		runs = 0;
@@ -180,18 +178,6 @@ function parseDecimalInteger(name: string, value: string): number {
 	return parsed;
 }
 
-export function printOptions(options: OptionsManager, infix = "") {
-	if (process.env.JAZZER_DEBUG) {
-		console.error(
-			util.formatWithOptions(
-				{ maxArrayLength: null, depth: null, colors: false },
-				`DEBUG: [core] Jazzer.js options ${infix}: \n%O`,
-				toOptionsWithPrintableSources(options),
-			),
-		);
-	}
-}
-
 function logInfoAboutFuzzerOptions(fuzzerOptions: string[]) {
 	fuzzerOptions.slice(1).forEach((element) => {
 		if (element.length > 0 && element[0] != "-") {
@@ -209,7 +195,7 @@ function optionDependentParams(
 	}
 
 	let opts = options.get("fuzzerOptions");
-	if (options.get("mode") === "regression") {
+	if (options.get("mode") === Mode.Regression) {
 		// The last provided option takes precedence
 		opts = opts.concat("-runs=0");
 	}

packages/jest-runner/config.test.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-import { OptionsManager, OptionSource } from "@jazzer.js/options";
+import { Mode, OptionsManager, OptionSource } from "@jazzer.js/options";
 
 import { loadConfig } from "./config";
 
@@ -46,12 +46,12 @@ describe("Config", () => {
 			);
 		});
 		it("default to regression mode", () => {
-			expect(loadConfig().get("mode")).toEqual("regression");
+			expect(loadConfig().get("mode")).toEqual(Mode.Regression);
 		});
 		it("set fuzzing mode based on environment variable", () => {
 			try {
 				process.env.JAZZER_FUZZ = "1";
-				expect(loadConfig().get("mode")).toEqual("fuzzing");
+				expect(loadConfig().get("mode")).toEqual(Mode.Fuzzing);
 			} finally {
 				delete process.env.JAZZER_FUZZ;
 			}

packages/jest-runner/config.ts

@@ -16,7 +16,12 @@
 
 import { cosmiconfigSync } from "cosmiconfig";
 
-import { Options, OptionsManager, OptionSource } from "@jazzer.js/options";
+import {
+	Mode,
+	Options,
+	OptionsManager,
+	OptionSource,
+} from "@jazzer.js/options";
 
 export const TIMEOUT_PLACEHOLDER = Number.MIN_SAFE_INTEGER;
 
@@ -29,7 +34,7 @@ export function loadConfig(
 
 	// Switch to fuzzing mode if environment variable `JAZZER_FUZZ` is set.
 	if (process.env.JAZZER_FUZZ) {
-		config.mode = "fuzzing";
+		config.mode = Mode.Fuzzing;
 	}
 	// Merge explicitly passed in options, e.g. coverage settings from Jest.
 	Object.assign(config, options);

packages/jest-runner/fuzz.test.ts

@@ -21,7 +21,7 @@ import * as tmp from "tmp";
 
 import { FindingAwareFuzzTarget, startFuzzingNoInit } from "@jazzer.js/core";
 import { FuzzTarget } from "@jazzer.js/fuzzer";
-import { OptionsManager, OptionSource } from "@jazzer.js/options";
+import { Mode, OptionsManager, OptionSource } from "@jazzer.js/options";
 
 import { Corpus } from "./corpus";
 import {
@@ -72,7 +72,7 @@ describe("fuzz", () => {
 			const inputPaths = mockInputPaths();
 			const fuzzingConfig = new OptionsManager(
 				OptionSource.DefaultJestOptions,
-			).merge({ mode: "fuzzing" }, OptionSource.ConfigurationFile);
+			).merge({ mode: Mode.Fuzzing }, OptionSource.ConfigurationFile);
 			await withMockTest(() => {
 				const originalTestNamePattern = jest
 					.fn()

packages/jest-runner/fuzz.ts

@@ -24,14 +24,15 @@ import {
 	FuzzTarget,
 	FuzzTargetAsyncOrValue,
 	FuzzTargetCallback,
-	printOptions,
 	startFuzzingNoInit,
 } from "@jazzer.js/core";
 import {
 	AllowedFuzzTestOptions,
+	Mode,
 	Options,
 	OptionsManager,
 	OptionSource,
+	printOptions,
 } from "@jazzer.js/options";
 
 import { Corpus } from "./corpus";
@@ -141,13 +142,13 @@ export function fuzz(
 
 		const wrappedFn = asFindingAwareFuzzFn(
 			fn,
-			localConfig.get("mode") === "fuzzing",
+			localConfig.get("mode") === Mode.Fuzzing,
 			localConfig.get("engine"),
 		);
 
-		if (localConfig.get("mode") === "regression") {
+		if (localConfig.get("mode") === Mode.Regression) {
 			runInRegressionMode(name, wrappedFn, corpus, localConfig, globals, mode);
-		} else if (localConfig.get("mode") === "fuzzing") {
+		} else if (localConfig.get("mode") === Mode.Fuzzing) {
 			runInFuzzingMode(name, wrappedFn, corpus, localConfig, globals, mode);
 		} else {
 			throw new Error(`Unknown mode ${localConfig.get("mode")}`);

packages/jest-runner/testStateInterceptor.test.ts

@@ -14,7 +14,12 @@
  * limitations under the License.
  */
 
-import { Options, OptionsManager, OptionSource } from "@jazzer.js/options";
+import {
+	Mode,
+	Options,
+	OptionsManager,
+	OptionSource,
+} from "@jazzer.js/options";
 
 import { interceptTestState } from "./testStateInterceptor";
 
@@ -32,7 +37,7 @@ describe("Test state interceptor", () => {
 	});
 
 	it("adjust test name pattern in regression mode", () => {
-		const { env, config } = mockEnvironment({ mode: "regression" });
+		const { env, config } = mockEnvironment({ mode: Mode.Regression });
 
 		const { originalTestNamePattern } = interceptTestState(env, config);
 
@@ -43,7 +48,7 @@ describe("Test state interceptor", () => {
 	});
 
 	it("do not adjust test name pattern in fuzzing mode", () => {
-		const { env, config } = mockEnvironment({ mode: "fuzzing" });
+		const { env, config } = mockEnvironment({ mode: Mode.Fuzzing });
 
 		const interceptedTestState = interceptTestState(env, config);
 
@@ -68,7 +73,7 @@ describe("Test state interceptor", () => {
 		}
 
 		const { env, config, originalHandleTestEvent } = mockEnvironment({
-			mode: "fuzzing",
+			mode: Mode.Fuzzing,
 		});
 
 		interceptTestState(env, config);
@@ -88,7 +93,7 @@ describe("Test state interceptor", () => {
 	});
 
 	it("deactivate Jest timeout in fuzzing mode", () => {
-		const { env, config } = mockEnvironment({ mode: "fuzzing" });
+		const { env, config } = mockEnvironment({ mode: Mode.Fuzzing });
 
 		const { currentTestTimeout } = interceptTestState(env, config);
 

packages/jest-runner/testStateInterceptor.ts

@@ -17,7 +17,7 @@
 import { JestEnvironment } from "@jest/environment";
 import { Circus } from "@jest/types";
 
-import { OptionsManager } from "@jazzer.js/options";
+import { Mode, OptionsManager } from "@jazzer.js/options";
 
 // Arbitrary high value to disable Jest timeout.
 const JEST_TIMEOUT_DISABLED = 1000 * 60 * 24 * 365;
@@ -47,7 +47,7 @@ export function interceptTestState(
 			// test inside. This breaks test name pattern matching, so remove "$" from the end of the pattern,
 			// and skip tests not matching the original pattern in the fuzz function.
 			if (
-				jazzerConfig.get("mode") == "regression" &&
+				jazzerConfig.get("mode") == Mode.Regression &&
 				state.testNamePattern?.source?.endsWith("$")
 			) {
 				originalTestNamePattern = state.testNamePattern;
@@ -60,7 +60,7 @@ export function interceptTestState(
 			// In fuzzing mode, only execute the first encountered (not skipped) fuzz test
 			// and mark all others as skipped.
 			if (
-				jazzerConfig.get("mode") === "fuzzing" &&
+				jazzerConfig.get("mode") === Mode.Fuzzing &&
 				event.test.mode !== "skip"
 			) {
 				if (
@@ -78,7 +78,7 @@ export function interceptTestState(
 		} else if (event.name === "test_fn_start") {
 			// Disable Jest timeout in fuzzing mode by setting it to a high value,
 			// otherwise Jest will kill the fuzz test after it's timeout (default 5 seconds).
-			if (jazzerConfig.get("mode") === "fuzzing") {
+			if (jazzerConfig.get("mode") === Mode.Fuzzing) {
 				state.testTimeout = JEST_TIMEOUT_DISABLED;
 			}
 			// Use configured timeout as fuzzing timeout as well. Every invocation

packages/options/index.ts

@@ -13,6 +13,14 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+import * as util from "util";
+
+export const Mode = {
+	Fuzzing: "fuzzing",
+	Regression: "regression",
+} as const;
+
+export type Mode = (typeof Mode)[keyof typeof Mode];
 
 export type LibAflOptions = {
 	mode: "fuzzing" | "regression";
@@ -65,7 +73,7 @@ export interface Options {
 	// Part of filepath names to include in the instrumentation.
 	includes: string[];
 	// Fuzzing mode.
-	mode: "fuzzing" | "regression";
+	mode: Mode;
 	// Whether to run the fuzzer in sync mode or not.
 	sync: boolean;
 	// Timeout for one fuzzing iteration in milliseconds.
@@ -115,7 +123,7 @@ export const defaultCLIOptions: Options = Object.freeze({
 	fuzzTarget: "",
 	idSyncFile: "",
 	includes: ["*"],
-	mode: "fuzzing",
+	mode: Mode.Fuzzing,
 	sync: false,
 	timeout: 5000,
 	verbose: false,
@@ -124,7 +132,7 @@ export const defaultCLIOptions: Options = Object.freeze({
 export const defaultJestOptions: Options = Object.freeze({
 	...defaultCLIOptions,
 	engine: "libfuzzer",
-	mode: "regression",
+	mode: Mode.Regression,
 });
 
 export type KeyFormatSource = (key: string) => string;
@@ -174,7 +182,6 @@ export enum OptionSource {
 }
 
 export type FuzzingEngine = Options["engine"];
-export type FuzzingMode = Options["mode"];
 
 export function resolveEngine(engine: string): FuzzingEngine {
 	switch (engine) {
@@ -190,16 +197,23 @@ export function resolveEngine(engine: string): FuzzingEngine {
 	}
 }
 
-export function resolveMode(mode: string): FuzzingMode {
-	switch (mode) {
-		case "fuzzing":
-		case "regression":
-			return mode;
-		default:
-			throw new Error(
-				`Unknown fuzzing mode '${mode}'. Supported modes are 'fuzzing' and 'regression'.`,
-			);
+function isOneOf<T extends Record<string, string>>(
+	obj: T,
+	value: string,
+): value is T[keyof T] {
+	return Object.values(obj).includes(value as T[keyof T]);
+}
+
+export function resolveMode(mode: string): Mode {
+	if (isOneOf(Mode, mode)) {
+		return mode;
 	}
+
+	throw new Error(
+		`Unknown fuzzer mode '${mode}'. Supported modes are ${Object.values(Mode)
+			.map((v) => `'${v}'`)
+			.join(", ")}.`,
+	);
 }
 
 type DefaultSourceInfo = {
@@ -455,6 +469,18 @@ export function toOptionsWithPrintableSources(
 	return result;
 }
 
+export function printOptions(options: OptionsManager, infix = "") {
+	if (process.env.JAZZER_DEBUG) {
+		console.error(
+			util.formatWithOptions(
+				{ maxArrayLength: null, depth: null, colors: false },
+				`DEBUG: [core] Jazzer.js options ${infix}: \n%O`,
+				toOptionsWithPrintableSources(options),
+			),
+		);
+	}
+}
+
 export function validateKeySource(key: keyof Options, source: OptionSource) {
 	const sourceName = defaultOptions[source].name;