@ni/jasmine-parameterized 0.2.0

package/README.md

@@ -0,0 +1,40 @@
+# Jasmine Parameterized
+
+The `@ni/jasmine-parameterized` library provides utility functions for writing [Jasmine](https://jasmine.github.io/) parameterized tests.
+
+# Usage
+
+1. Install in your app's `devDependencies`:
+
+    ```
+    npm install -D @ni/jasmine-parameterized
+    ```
+
+2. Use `parameterizeSpec` to write strictly-typed jasmine tests that run for different test scenarios, where each test can be focused or excluded as needed by name.
+
+### `parameterizeSpec`
+Use `parameterizeSpec` to create a parameterized test using an array of tests with names.
+
+In the following example:
+    - the test named `cats-and-dogs` is focused for debugging
+    - the test named `frogs` is configured to always be disabled
+    - the test named `men` will run normally as it has no override
+
+```ts
+import { parameterizeSpec } from '@ni/jasmine-parameterized';
+const rainTests = [
+    { name: 'cats-and-dogs', type: 'idiom' },
+    { name: 'frogs' type: 'idiom'},
+    { name: 'men', type: 'lyrics'}
+] as const;
+describe('Different rains', () => {
+    parameterizeSpec(rainTests, (spec, name, value) => {
+        spec(`of type ${name} exist`, () => {
+            expect(value.type).toBeDefined();
+        });
+    }, {
+        'cats-and-dogs': fit,
+        frogs: xit
+    });
+});
+```

package/dist/esm/index.d.ts

@@ -0,0 +1 @@
+export { parameterizeSpec } from './parameterized.js';

package/dist/esm/index.js

@@ -0,0 +1,2 @@
+export { parameterizeSpec } from './parameterized.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC","sourcesContent":["export { parameterizeSpec } from './parameterized.js';\n"]}

package/dist/esm/parameterized.d.ts

@@ -0,0 +1,72 @@
+/// <reference types="jasmine" />
+declare type Fit = typeof fit;
+declare type Xit = typeof xit;
+declare type It = typeof it;
+/**
+ * One of the jasmine spec functions: fit, xit, or it
+ */
+declare type Spec = Fit | Xit | It;
+/**
+ * One of the jasmine spec functions: fit or xit
+ */
+declare type SpecOverride = Fit | Xit;
+/**
+ * Used to create a parameterized test using an object of test names and arbitrary test values.
+ * In the following example:
+ *  - the test named `catsAndDogs` is focused for debugging
+ *  - the test named `frogs` is configured to always be disabled
+ *  - the test named `men` will run normally as it has no override
+ * @example
+ * const rainTests = {
+ *     catsAndDogs: 'idiom',
+ *     frogs: 'idiom',
+ *     men: 'lyrics'
+ * } as const;
+ * describe('Different rains', () => {
+ *     parameterize(rainTests, (spec, name, value) => {
+ *         spec(`of type ${name} exist`, () => {
+ *             expect(value).toBeDefined();
+ *         });
+ *     }, {
+ *         catsAndDogs: fit,
+ *         frogs: xit
+ *     });
+ * });
+ */
+export declare const parameterize: <T extends object>(testCases: T, test: (spec: Spec, name: keyof T, value: T[keyof T]) => void, specOverrides?: { [P in keyof T]?: SpecOverride | undefined; } | undefined) => void;
+declare type ObjectFromNamedList<T extends readonly {
+    name: string;
+}[]> = {
+    [K in T extends readonly {
+        name: infer U;
+    }[] ? U : never]: T[number];
+};
+/**
+ * Used to create a parameterized test using an array of tests with names.
+ * In the following example:
+ *  - the test named `cats-and-dogs` is focused for debugging
+ *  - the test named `frogs` is configured to always be disabled
+ *  - the test named `men` will run normally as it has no override
+ * @example
+ * const rainTests = [
+ *   { name: 'cats-and-dogs', type: 'idiom' },
+ *   { name: 'frogs' type: 'idiom'},
+ *   { name: 'men', type: 'lyrics'}
+ * ] as const;
+ * describe('Different rains', () => {
+ *     parameterizeSpec(rainTests, (spec, name, value) => {
+ *         spec(`of type ${name} exist`, () => {
+ *             expect(value.type).toBeDefined();
+ *         });
+ *     }, {
+ *         'cats-and-dogs': fit,
+ *         frogs: xit
+ *     });
+ * });
+ */
+export declare const parameterizeSpec: <T extends readonly {
+    name: string;
+}[]>(list: T, test: (spec: Spec, name: T extends readonly {
+    name: infer U;
+}[] ? U : never, value: T[number]) => void, specOverrides?: (ObjectFromNamedList<T> extends infer T_1 ? { [P in keyof T_1]?: SpecOverride | undefined; } : never) | undefined) => void;
+export {};

package/dist/esm/parameterized.js

@@ -0,0 +1,75 @@
+/**
+ * Used to create a parameterized test using an object of test names and arbitrary test values.
+ * In the following example:
+ *  - the test named `catsAndDogs` is focused for debugging
+ *  - the test named `frogs` is configured to always be disabled
+ *  - the test named `men` will run normally as it has no override
+ * @example
+ * const rainTests = {
+ *     catsAndDogs: 'idiom',
+ *     frogs: 'idiom',
+ *     men: 'lyrics'
+ * } as const;
+ * describe('Different rains', () => {
+ *     parameterize(rainTests, (spec, name, value) => {
+ *         spec(`of type ${name} exist`, () => {
+ *             expect(value).toBeDefined();
+ *         });
+ *     }, {
+ *         catsAndDogs: fit,
+ *         frogs: xit
+ *     });
+ * });
+ */
+export const parameterize = (testCases, test, specOverrides) => {
+    const testCaseNames = Object.keys(testCases);
+    if (specOverrides) {
+        const overrideNames = Object.keys(specOverrides);
+        if (!overrideNames.every(overrideName => testCaseNames.includes(overrideName))) {
+            throw new Error('Parameterized test override names must match test case name');
+        }
+        if (
+        // eslint-disable-next-line no-restricted-globals
+        !overrideNames.every(overrideName => [fit, xit].includes(specOverrides[overrideName]))) {
+            throw new Error('Must configure override with one of the jasmine spec functions: fit or xit');
+        }
+    }
+    testCaseNames.forEach(testCaseName => {
+        const spec = specOverrides?.[testCaseName] ?? it;
+        test(spec, testCaseName, testCases[testCaseName]);
+    });
+};
+/**
+ * Used to create a parameterized test using an array of tests with names.
+ * In the following example:
+ *  - the test named `cats-and-dogs` is focused for debugging
+ *  - the test named `frogs` is configured to always be disabled
+ *  - the test named `men` will run normally as it has no override
+ * @example
+ * const rainTests = [
+ *   { name: 'cats-and-dogs', type: 'idiom' },
+ *   { name: 'frogs' type: 'idiom'},
+ *   { name: 'men', type: 'lyrics'}
+ * ] as const;
+ * describe('Different rains', () => {
+ *     parameterizeSpec(rainTests, (spec, name, value) => {
+ *         spec(`of type ${name} exist`, () => {
+ *             expect(value.type).toBeDefined();
+ *         });
+ *     }, {
+ *         'cats-and-dogs': fit,
+ *         frogs: xit
+ *     });
+ * });
+ */
+export const parameterizeSpec = (list, test, specOverrides) => {
+    const testCases = list.reduce((result, entry) => {
+        if (result[entry.name]) {
+            throw new Error(`Duplicate name found in test case list: ${entry.name}. Make sure all test names are unique.`);
+        }
+        result[entry.name] = entry;
+        return result;
+    }, {});
+    parameterize(testCases, test, specOverrides);
+};
+//# sourceMappingURL=parameterized.js.map

package/dist/esm/parameterized.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parameterized.js","sourceRoot":"","sources":["../../src/parameterized.ts"],"names":[],"mappings":"AAiBA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CACxB,SAAY,EACZ,IAA4D,EAC5D,aAEC,EACG,EAAE;IACN,MAAM,aAAa,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,CAAgB,CAAC;IAC5D,IAAI,aAAa,EAAE;QACf,MAAM,aAAa,GAAG,MAAM,CAAC,IAAI,CAC7B,aAAa,CACkB,CAAC;QACpC,IACI,CAAC,aAAa,CAAC,KAAK,CAAC,YAAY,CAAC,EAAE,CAAC,aAAa,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,EAC5E;YACE,MAAM,IAAI,KAAK,CACX,6DAA6D,CAChE,CAAC;SACL;QACD;QACI,iDAAiD;QACjD,CAAC,aAAa,CAAC,KAAK,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,QAAQ,CAAC,aAAa,CAAC,YAAY,CAAE,CAAC,CAAC,EACzF;YACE,MAAM,IAAI,KAAK,CACX,4EAA4E,CAC/E,CAAC;SACL;KACJ;IACD,aAAa,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE;QACjC,MAAM,IAAI,GAAG,aAAa,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,CAAC;QACjD,IAAI,CAAC,IAAI,EAAE,YAAY,EAAE,SAAS,CAAC,YAAY,CAAC,CAAC,CAAC;IACtD,CAAC,CAAC,CAAC;AACP,CAAC,CAAC;AAMF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAC5B,IAAO,EACP,IAIS,EACT,aAEC,EACG,EAAE;IACN,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,CACzB,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE;QACd,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE;YACpB,MAAM,IAAI,KAAK,CACX,2CAA2C,KAAK,CAAC,IAAI,wCAAwC,CAChG,CAAC;SACL;QACD,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;QAC3B,OAAO,MAAM,CAAC;IAClB,CAAC,EACD,EAAE,CACqB,CAAC;IAC5B,YAAY,CAAyB,SAAS,EAAE,IAAI,EAAE,aAAa,CAAC,CAAC;AACzE,CAAC,CAAC","sourcesContent":["// The following aliases are just to reduce the number\n// of eslint disables in this source file. In normal\n// test code use the globals directly so eslint can\n// guard accidental check-ins of fit, etc.\n// eslint-disable-next-line no-restricted-globals\ntype Fit = typeof fit;\ntype Xit = typeof xit;\ntype It = typeof it;\n/**\n * One of the jasmine spec functions: fit, xit, or it\n */\ntype Spec = Fit | Xit | It;\n/**\n * One of the jasmine spec functions: fit or xit\n */\ntype SpecOverride = Fit | Xit;\n\n/**\n * Used to create a parameterized test using an object of test names and arbitrary test values.\n * In the following example:\n *  - the test named `catsAndDogs` is focused for debugging\n *  - the test named `frogs` is configured to always be disabled\n *  - the test named `men` will run normally as it has no override\n * @example\n * const rainTests = {\n *     catsAndDogs: 'idiom',\n *     frogs: 'idiom',\n *     men: 'lyrics'\n * } as const;\n * describe('Different rains', () => {\n *     parameterize(rainTests, (spec, name, value) => {\n *         spec(`of type ${name} exist`, () => {\n *             expect(value).toBeDefined();\n *         });\n *     }, {\n *         catsAndDogs: fit,\n *         frogs: xit\n *     });\n * });\n */\nexport const parameterize = <T extends object>(\n    testCases: T,\n    test: (spec: Spec, name: keyof T, value: T[keyof T]) => void,\n    specOverrides?: {\n        [P in keyof T]?: SpecOverride;\n    }\n): void => {\n    const testCaseNames = Object.keys(testCases) as (keyof T)[];\n    if (specOverrides) {\n        const overrideNames = Object.keys(\n            specOverrides\n        ) as (keyof typeof specOverrides)[];\n        if (\n            !overrideNames.every(overrideName => testCaseNames.includes(overrideName))\n        ) {\n            throw new Error(\n                'Parameterized test override names must match test case name'\n            );\n        }\n        if (\n            // eslint-disable-next-line no-restricted-globals\n            !overrideNames.every(overrideName => [fit, xit].includes(specOverrides[overrideName]!))\n        ) {\n            throw new Error(\n                'Must configure override with one of the jasmine spec functions: fit or xit'\n            );\n        }\n    }\n    testCaseNames.forEach(testCaseName => {\n        const spec = specOverrides?.[testCaseName] ?? it;\n        test(spec, testCaseName, testCases[testCaseName]);\n    });\n};\n\ntype ObjectFromNamedList<T extends readonly { name: string }[]> = {\n    [K in T extends readonly { name: infer U }[] ? U : never]: T[number];\n};\n\n/**\n * Used to create a parameterized test using an array of tests with names.\n * In the following example:\n *  - the test named `cats-and-dogs` is focused for debugging\n *  - the test named `frogs` is configured to always be disabled\n *  - the test named `men` will run normally as it has no override\n * @example\n * const rainTests = [\n *   { name: 'cats-and-dogs', type: 'idiom' },\n *   { name: 'frogs' type: 'idiom'},\n *   { name: 'men', type: 'lyrics'}\n * ] as const;\n * describe('Different rains', () => {\n *     parameterizeSpec(rainTests, (spec, name, value) => {\n *         spec(`of type ${name} exist`, () => {\n *             expect(value.type).toBeDefined();\n *         });\n *     }, {\n *         'cats-and-dogs': fit,\n *         frogs: xit\n *     });\n * });\n */\nexport const parameterizeSpec = <T extends readonly { name: string }[]>(\n    list: T,\n    test: (\n        spec: Spec,\n        name: keyof ObjectFromNamedList<T>,\n        value: T[number]\n    ) => void,\n    specOverrides?: {\n        [P in keyof ObjectFromNamedList<T>]?: SpecOverride;\n    }\n): void => {\n    const testCases = list.reduce<{ [key: string]: { name: string } }>(\n        (result, entry) => {\n            if (result[entry.name]) {\n                throw new Error(\n                    `Duplicate name found in test case list: ${entry.name}. Make sure all test names are unique.`\n                );\n            }\n            result[entry.name] = entry;\n            return result;\n        },\n        {}\n    ) as ObjectFromNamedList<T>;\n    parameterize<ObjectFromNamedList<T>>(testCases, test, specOverrides);\n};\n"]}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@ni/jasmine-parameterized",
+  "version": "0.2.0",
+  "description": "A utility to write parameterized jasmine tests",
+  "scripts": {
+    "build": "tsc -b",
+    "lint": "eslint .",
+    "format": "eslint . --fix",
+    "pack": "npm pack",
+    "invoke-publish": "npm publish",
+    "tdd": "npm run build && npm run test",
+    "test": "npm run test:node && npm run test:browser",
+    "test:node": "jasmine",
+    "test:browser": "karma start karma.conf.cjs --browsers=ChromeHeadlessOpt --single-run",
+    "test:browser:debugger": "karma start karma.conf.cjs --browsers=ChromeDebugging"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ni/nimble.git",
+    "directory": "packages/jasmine-parameterized"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      }
+    }
+  },
+  "types": "./dist/esm/index.d.ts",
+  "author": "National Instruments",
+  "license": "MIT",
+  "devDependencies": {
+    "@ni/eslint-config-javascript": "^4.2.0",
+    "@ni/eslint-config-typescript": "^4.2.0",
+    "@types/jasmine": "^4.3.1",
+    "jasmine": "^4.2.0",
+    "jasmine-core": "^4.5.0",
+    "karma": "^6.3.0",
+    "karma-jasmine": "^5.1.0",
+    "karma-jasmine-html-reporter": "^2.0.0",
+    "karma-spec-reporter": "^0.0.36",
+    "playwright": "^1.30.0",
+    "typescript": "~4.8.2"
+  }
+}