[2.4.0 stack 13/18] Testing: fast-check properties, expectTypeOf signature pins and benchmarks in every test file

.github/workflows/tests.yml

@@ -64,6 +64,9 @@
         with:
           persist-credentials: false
 
+      - name: Setup
+        uses: ./.github/actions/setup
+
       - name: Setup Bun
         uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
 
@@ -81,13 +84,16 @@
         with:
           persist-credentials: false
 
+      - name: Setup
+        uses: ./.github/actions/setup
+
       - name: Setup Deno
         uses: denoland/setup-deno@22d081ff2d3a40755e97629de92e3bcbfa7cf2ed # v2.0.5
         with:
           deno-version: v2.x
 
       - name: Run tests
-        run: deno test --unstable-sloppy-imports --allow-net src
+        run: deno test --unstable-sloppy-imports --allow-net --allow-env src
 
   test-browsers:
     name: Test on Browsers (${{ matrix.browser }})

CONTRIBUTING.md

@@ -76,7 +76,16 @@ example `formatSomething`):
    or `src/is-valid-service-phone/is-valid-service-phone.ts` for examples).
 3. Add tests alongside it in `src/format-something/format-something.test.ts`. Cover valid input,
    invalid/edge-case input, and options, if any. Tests must pass on Node, Bun and Deno (see
-   `npm test:bun` / `npm test:deno` under Useful scripts).
+   `npm test:bun` / `npm test:deno` under Useful scripts). Expectations are hand-written literals,
+   never values computed by the code under test. Close the file with a `describe("properties")`
+   block of [fast-check](https://fast-check.dev) properties that hold by specification (a
+   generated value is valid, format/parse round-trip, masks never change the verdict, arbitrary
+   input never throws) and a `describe("<name> types")` block that pins the public signature with
+   `expectTypeOf` (parameters, options and return type; `vp check` fails on a wrong assertion). A
+   hot path may also get a `describe("<name> benchmarks")` block of `bench` cases: they are todo
+   entries in a normal run and execute with `npx vp test bench --run`. `describe`, `test`,
+   `expect`, `expectTypeOf` and `bench` all come from `src/_internals/test/runtime`, which maps
+   them to vitest, Bun or Deno.
 4. Export the new function (and any exported types) from `src/index.ts`, keeping the existing
    alphabetical ordering. Then add the function name to the `PUBLIC` list and the type(s) to the
    `publicTypes` map in `src/index.test.ts`, alphabetically. These two make up the package's

package.json

@@ -112,6 +112,7 @@
 		"@vitest/browser-webdriverio": "4.1.11",
 		"@vitest/coverage-v8": "4.1.11",
 		"esbuild": "0.27.2",
+		"fast-check": "4.10.0",
 		"jscpd": "5.2.0",
 		"knip": "6.35.1",
 		"lockfile-lint": "5.0.1",

src/_internals/test/arbitraries.ts

@@ -0,0 +1,132 @@
+import * as fc from "fast-check";
+
+import { HOLIDAYS_MAX_YEAR, HOLIDAYS_MIN_YEAR } from "../constants/holidays";
+import { DATA as STATES, type StateCode } from "../constants/states";
+
+/**
+ * Spreads `separators` around every character of `value`: one before the first character, one
+ * between each pair and one after the last, so `separators` must hold `value.length + 1` entries.
+ * @param {string} value The characters to spread the separators around.
+ * @param {string[]} separators The separators to place around each character.
+ * @returns {string} The interleaved value.
+ */
+const interleave = (value: string, separators: string[]): string => {
+	let result = separators[0];
+
+	for (let index = 0; index < value.length; index++) {
+		result += `${value[index]}${separators[index + 1]}`;
+	}
+
+	return result;
+};
+
+const anyPrimitive: fc.Arbitrary<unknown> = fc.oneof(fc.string(), fc.integer(), fc.boolean());
+
+/** Any grapheme string: the widest text a util is expected to survive. */
+export const anyText: fc.Arbitrary<string> = fc.string({ unit: "grapheme" });
+
+/** Text, numbers, booleans, `undefined`, `null` and arrays: what a caller may pass by mistake. */
+export const anyValue: fc.Arbitrary<unknown> = fc.oneof(
+	anyText,
+	fc.double(),
+	fc.boolean(),
+	fc.constantFrom(undefined, null),
+	fc.array(fc.string()),
+);
+
+/** ASCII alphanumeric text, at most twelve characters long. */
+export const asciiAlphanumericText: fc.Arbitrary<string> = fc.stringMatching(/^[0-9A-Za-z]{0,12}$/);
+
+/** Booleans, `null`, numbers, strings, arrays and plain objects, including nested primitives. */
+export const anyGarbage: fc.Arbitrary<unknown> = fc.oneof(
+	fc.boolean(),
+	fc.constant(null),
+	fc.double(),
+	fc.string(),
+	fc.array(anyPrimitive),
+	fc.object({ key: fc.constantFrom("a", "b", "c") }),
+);
+
+/**
+ * @param {number} length How many digits the generated value holds.
+ * @returns {fc.Arbitrary<string>} Strings of exactly `length` digits.
+ */
+export const digits = (length: number): fc.Arbitrary<string> =>
+	fc.stringMatching(new RegExp(`^[0-9]{${length}}$`));
+
+/**
+ * @param {number} maxLength The largest number of digits the generated value holds.
+ * @returns {fc.Arbitrary<string>} Strings of zero up to `maxLength` digits.
+ */
+export const digitsUpTo = (maxLength: number): fc.Arbitrary<string> =>
+	fc.stringMatching(new RegExp(`^[0-9]{0,${maxLength}}$`));
+
+/**
+ * @param {number} maxLength The largest number of digits the generated value holds.
+ * @param {number[]} lengths The lengths to leave out.
+ * @returns {fc.Arbitrary<string>} Digit strings whose length is none of `lengths`.
+ */
+export const digitsOfOtherLength = (maxLength: number, lengths: number[]): fc.Arbitrary<string> =>
+	digitsUpTo(maxLength).filter((value) => !lengths.includes(value.length));
+
+/**
+ * @param {string[]} maskChars The characters a separator is built from.
+ * @param {number} count How many separators the generated array holds.
+ * @param {number} maxLength The largest length of a single separator.
+ * @returns {fc.Arbitrary<string[]>} Arrays of exactly `count` separators.
+ */
+export const maskSeparators = (
+	maskChars: string[],
+	count: number,
+	maxLength: number,
+): fc.Arbitrary<string[]> =>
+	fc.array(fc.string({ unit: fc.constantFrom(...maskChars), maxLength }), {
+		minLength: count,
+		maxLength: count,
+	});
+
+/**
+ * @param {fc.Arbitrary<string>} source The values to spread the mask over.
+ * @param {string[]} maskChars The characters a separator is built from.
+ * @param {number} maxLength The largest length of a single separator.
+ * @returns {fc.Arbitrary<string>} Values of `source` with a separator around every character.
+ */
+export const maskedValues = (
+	source: fc.Arbitrary<string>,
+	maskChars: string[],
+	maxLength: number,
+): fc.Arbitrary<string> =>
+	source.chain((value) =>
+		maskSeparators(maskChars, value.length + 1, maxLength).map((separators) =>
+			interleave(value, separators),
+		),
+	);
+
+/** The two letter code of every Brazilian state. */
+export const stateCodes: fc.Arbitrary<StateCode> = fc.constantFrom(
+	...STATES.map((state) => state.code),
+);
+
+/** A year covered by the bundled holiday tables. */
+export const holidayYears: fc.Arbitrary<number> = fc.integer({
+	min: HOLIDAYS_MIN_YEAR,
+	max: HOLIDAYS_MAX_YEAR,
+});
+
+/** A zero based month index, as `Date` numbers them. */
+export const monthIndexes: fc.Arbitrary<number> = fc.integer({ min: 0, max: 11 });
+
+/** A day of the month that exists in every month, February included. */
+export const monthDays: fc.Arbitrary<number> = fc.integer({ min: 1, max: 28 });
+
+/** A valid date inside the range the business day utils are exercised over. */
+export const businessDayDates: fc.Arbitrary<Date> = fc.date({
+	min: new Date(1950, 0, 1),
+	max: new Date(2050, 11, 31),
+	noInvalidDate: true,
+});
+
+/** An amount with at most two decimals, the precision currency formatting round-trips. */
+export const twoDecimalAmounts: fc.Arbitrary<number> = fc
+	.integer({ min: -1_000_000_000, max: 1_000_000_000 })
+	.map((cents) => cents / 100);

src/_internals/test/globals.d.ts

@@ -12,6 +12,12 @@ declare const Deno: {
 	}) => void;
 };
 
+interface ImportMeta {
+	readonly env: {
+		readonly MODE: string;
+	};
+}
+
 declare global {
 	var RUN_LIVE_CEP_TESTS: string | number | undefined;
 }

src/_internals/test/noop.ts

@@ -0,0 +1,18 @@
+import { type bench as vitestBench, type expectTypeOf as vitestExpectTypeOf } from "vite-plus/test";
+
+const chain: unknown = new Proxy(() => chain, { apply: () => chain, get: () => chain });
+
+/**
+ * Runtime stand-in for vitest's `expectTypeOf` on Bun and Deno: every call and property access
+ * returns the same chainable no-op, so a `describe("<name> types")` block runs without effect
+ * there. The assertions themselves are checked statically by `vp check` and by
+ * `npm run test:types`.
+ */
+export const expectTypeOf = chain as typeof vitestExpectTypeOf;
+
+/**
+ * Runtime stand-in for vitest's `bench` outside benchmark mode (vitest in test mode, Bun, Deno):
+ * a `describe("<name> benchmarks")` block registers nothing there. `npm run bench` runs vitest in
+ * benchmark mode, where the real `bench` is used and the `test` blocks are ignored instead.
+ */
+export const bench = chain as typeof vitestBench;