@tapjs/test - npm Package Compare versions

Comparing version 0.0.0-15 to 0.0.0-16

package.json

 {
   "name": "@tapjs/test",
-  "version": "0.0.0-15",
+  "version": "0.0.0-16",
   "description": "the pluggable Test class for node-tap",
@@ -54,3 +54,3 @@ "author": "Isaac Z. Schlueter <[e-mail]> (https://blog.izs.me)",
   "peerDependencies": {
-    "@tapjs/core": "0.0.0-15"
+    "@tapjs/core": "0.0.0-16"
   },
@@ -70,3 +70,6 @@ "dependencies": {
     "url": "git+https://github.com/tapjs/tapjs.git"
+  },
+  "engines": {
+    "node": ">=16"
   }
 }

README.md

 # `@tapjs/test`
 
 The plugin-ified `Test` class in node-tap.
+
+## Class `Test`
+
+This is the object that's actually provided to your tests. When
+you do `t.pass('this is fine')`, this is the `t`.
+
+It's also the base class of the `TAP` class which is the default
+export of the `'tap'` module, so anything on `Test` is also on
+`TAP`.
+
+The `Test` class itself adds only the following methods, but it
+has the sum of all methods provided by all loaded plugins.
+
+### `t.applyPlugin(plugin: TapPlugin): Test`
+
+This returns a new version of the Test object which has the
+plugin applied.
+
+Note that it's actually a different object, but anything done to
+the copy will also affect the base, and it will inherit all
+properties and methods that the base has, so the new object can
+be used in place of the original.
+
+For example:
+
+```js
+import t from 'tap'
+
+const plugin = t => ({
+  hello: () => console.log('hello from ', t.name),
+  blowUp: () => t.fail('blowing up')
+})
+
+t.test('apply a plugin', original => {
+  const t = original.applyPlugin(plugin)
+  console.log(typeof original.hello) // 'undefined'
+  console.log(typeof t.hello) // 'function'
+  t.hello()
+  t.blowUp()
+  console.log(original.passing()) // false
+  t.end() // ends the subtest
+})
+```
+
+### `t.pluginLoaded(plugin: TapPlugin): boolean`
+
+Returns true if the plugin is loaded.
+
+Also asserts that `t` implements the type returned by the plugin
+function.
+
+So, for example, if a plugin _might_ be loaded, you can use this
+to get TypeScript to know about it.
+
+```ts
+import t from 'tap'
+import { Test } from '@tapjs/test'
+
+const plugin = t => ({
+  hello: () => console.log('hello from ', t.name),
+  blowUp: () => t.fail('blowing up')
+})
+
+const maybeBlowup = (t: Test) => {
+  if (t.pluginLoaded(plugin)) {
+    t.blowUp()
+  } else {
+    t.pass('no blowup required')
+  }
+}
+
+t.test('maybe blow up', original => {
+  const t = original.applyPlugin(plugin)
+  maybeBlowup(original) // emits passing 'no blowup required'
+  maybeBlowup(t) // blows up
+  t.end()
+})
+```
+
+### `t.test()`, `t.todo()`, `t.skip()`
+
+Creates a subtest. You've seen this one before. This is the class
+that implements it.
+
+## `signature: string`
+
+The signature of the plugins built into this Test class.
+
+## `loaders: string[]`
+
+The loaders added by plugins.
+
+## `testFileExtensions: Set<string>`
+
+The test file extensions added by plugins.

scripts/test-template.ts

@@ -23,2 +23,10 @@ //{{HEADER COMMENT START}}
 
+/**
+ * The set of file extensions that the tap runner will load
+ * by default. Expaned into the `include` config values if they
+ * contain the token `__EXTENSIONS__`.
+ *
+ * If plugins export a `testFileExtensions` string array, then the
+ * entries will be added to this set.
+ */
 export const testFileExtensions = new Set(['js', 'cjs', 'mjs'])
@@ -70,2 +78,6 @@ //{{FILE TYPES START}}
 
+/**
+ * Utility type to combine the array of plugins into a single combined
+ * return type.
+ */
 export type PluginResult<
@@ -80,2 +92,5 @@ P extends ((t: TestBase, opts: any) => any)[]
 
+/**
+ * The union of return types of an array of functions
+ */
 type AnyReturnValue<A extends ((...a: any[]) => any)[]> = A extends [
@@ -103,3 +118,6 @@ infer H extends (...a: any[]) => any,
 
-// options
+/**
+ * Utility type to get the second parameter of a function, used to
+ * get the types of all plugin options.
+ */
 export type SecondParam<T extends [any] | [any, any]> = T extends [
@@ -134,3 +152,10 @@ any,
 
+/**
+ * Type that is the array of all plugin functions loaded
+ */
 //{{PLUGINS CODE START}}
+export type PluginSet = (
+  | TapPlugin<any>
+  | TapPlugin<any, TestBaseOpts>
+)[]
 const plugins = () => {
@@ -140,8 +165,8 @@ if (plugins_) return plugins_
 }
-export type PluginSet = (
-  | TapPlugin<any>
-  | TapPlugin<any, TestBaseOpts>
-)[]
 //{{PLUGINS CODE END}}
 
+/**
+ * The combined configuration object generated by the `config`
+ * objects exported by plugins.
+ */
 //{{PLUGINS CONFIG START}}
@@ -160,2 +185,7 @@ // just referenced to keep prettier/tslint happy
 
+/**
+ * The string signature that lists all loaded plugins alphabetically, used
+ * to determine whether a rebuild is necessary by comparing it to the `plugin`
+ * config value.
+ */
 //{{PLUGIN SIGNATURE START}}
@@ -166,4 +196,4 @@ export const signature = ''
 /**
- * Union type of {@link @tapjs/core!test-base.TestBase} plus all plugin return
- * values
+ * Union of {@link @tapjs/core!test-base.TestBase} plus all plugin
+ * return values
  */
@@ -175,2 +205,5 @@ export type TTest<P extends PluginSet = PluginSet> = TestBase &
  * Interface that is the assembled result of every loaded plugin.
+ *
+ * This is extended into an interface because otherwise the code
+ * hinting is overwhelmingly extravagant.
  */
@@ -305,2 +338,8 @@ export interface BuiltPlugins extends PluginResult<PluginSet> {}
 const kClass = Symbol('@tapjs/test construction class')
+/**
+ * Option object used when extending the `Test` class via
+ * {@link @tapjs/test!index.Test.applyPlugin}
+ *
+ * @internal
+ */
 export type PluginExtensionOption<
@@ -307,0 +346,0 @@ E extends BuiltPlugins = BuiltPlugins,

scripts/tsconfig.json

 {
   "compilerOptions": {
+    "rootDir": "./src",
     "declaration": true,
@@ -4,0 +5,0 @@ "declarationMap": true,

test-built/dist/cjs/index.d.ts

@@ -17,3 +17,15 @@ import { PromiseWithSubtest, TapPlugin, TestBase, TestBaseOpts } from '@tapjs/core';
 import type { ConfigSet, Jack } from 'jackspeak';
+/**
+ * The set of file extensions that the tap runner will load
+ * by default. Expaned into the `include` config values if they
+ * contain the token `__EXTENSIONS__`.
+ *
+ * If plugins export a `testFileExtensions` string array, then the
+ * entries will be added to this set.
+ */
 export declare const testFileExtensions: Set<string>;
+/**
+ * Utility type to combine the array of plugins into a single combined
+ * return type.
+ */
 export type PluginResult<P extends ((t: TestBase, opts: any) => any)[]> = P extends [
@@ -23,2 +35,6 @@ infer H extends (t: TestBase, opts: any) => any,
 ] ? ReturnType<H> & PluginResult<T> : {};
+/**
+ * Utility type to get the second parameter of a function, used to
+ * get the types of all plugin options.
+ */
 export type SecondParam<T extends [any] | [any, any]> = T extends [
@@ -42,2 +58,5 @@ any,
 export type TestOpts = TestBaseOpts & PluginOpts<PluginSet>;
+/**
+ * Type that is the array of all plugin functions loaded
+ */
 export type PluginSet = [
@@ -59,2 +78,6 @@ typeof Plugin_after.plugin,
 ];
+/**
+ * The combined configuration object generated by the `config`
+ * objects exported by plugins.
+ */
 export declare const config: <C extends ConfigSet>(jack: Jack<C>) => Jack<C & import("jackspeak").ConfigSetFromMetaSet<"boolean", false, {
@@ -96,2 +119,6 @@ only: {
     invert: {
+        /**
+         * Utility type to combine the array of plugins into a single combined
+         * return type.
+         */
         type: string;
@@ -176,7 +203,17 @@ short: string;
 }>>;
+/**
+ * The set of `loader` strings exported by plugins. If a plugin exports
+ * `preload = true`, then it will be sorted to the start of this list, so
+ * that Node loads it before other loaders.
+ */
 export declare const loaders: string[];
+/**
+ * The string signature that lists all loaded plugins alphabetically, used
+ * to determine whether a rebuild is necessary by comparing it to the `plugin`
+ * config value.
+ */
 export declare const signature = "@tapjs/after\n@tapjs/after-each\n@tapjs/asserts\n@tapjs/before\n@tapjs/before-each\n@tapjs/filter\n@tapjs/fixture\n@tapjs/intercept\n@tapjs/mock\n@tapjs/snapshot\n@tapjs/spawn\n@tapjs/stdin\n@tapjs/typescript\n@tapjs/worker";
 /**
- * Union type of {@link @tapjs/core!test-base.TestBase} plus all plugin return
- * values
+ * Union of {@link @tapjs/core!test-base.TestBase} plus all plugin
+ * return values
  */
@@ -186,2 +223,5 @@ export type TTest<P extends PluginSet = PluginSet> = TestBase & PluginResult<P>;
  * Interface that is the assembled result of every loaded plugin.
+ *
+ * This is extended into an interface because otherwise the code
+ * hinting is overwhelmingly extravagant.
  */
@@ -192,2 +232,8 @@ export interface BuiltPlugins extends PluginResult<PluginSet> {
 declare const kClass: unique symbol;
+/**
+ * Option object used when extending the `Test` class via
+ * {@link @tapjs/test!index.Test.applyPlugin}
+ *
+ * @internal
+ */
 export type PluginExtensionOption<E extends BuiltPlugins = BuiltPlugins, O extends TestOpts = TestOpts> = {
@@ -194,0 +240,0 @@ [kPluginSet]: TapPlugin<any, O>[];

test-built/dist/cjs/index.js

@@ -48,2 +48,10 @@ "use strict";
 const node_util_1 = require("node:util");
+/**
+ * The set of file extensions that the tap runner will load
+ * by default. Expaned into the `include` config values if they
+ * contain the token `__EXTENSIONS__`.
+ *
+ * If plugins export a `testFileExtensions` string array, then the
+ * entries will be added to this set.
+ */
 exports.testFileExtensions = new Set(['js', 'cjs', 'mjs']);
@@ -85,11 +93,2 @@ //{{FILE TYPES START}}
 let plugins_;
-//{{PLUGINS CODE START}}
-// const plugins = () => {
-//   if (plugins_) return plugins_
-//   return (plugins_ = [])
-// }
-// export type PluginSet = (
-//   | TapPlugin<any>
-//   | TapPlugin<any, TestBaseOpts>
-// )[]
 const plugins = () => {
@@ -116,2 +115,6 @@ if (plugins_)
 //{{PLUGINS CODE END}}
+/**
+ * The combined configuration object generated by the `config`
+ * objects exported by plugins.
+ */
 //{{PLUGINS CONFIG START}}
@@ -173,2 +176,7 @@ // // just referenced to keep prettier/tslint happy
 ]);
+/**
+ * The set of `loader` strings exported by plugins. If a plugin exports
+ * `preload = true`, then it will be sorted to the start of this list, so
+ * that Node loads it before other loaders.
+ */
 exports.loaders = [
@@ -179,2 +187,7 @@ "@tapjs/mock/loader",
 //{{LOADERS END}}
+/**
+ * The string signature that lists all loaded plugins alphabetically, used
+ * to determine whether a rebuild is necessary by comparing it to the `plugin`
+ * config value.
+ */
 //{{PLUGIN SIGNATURE START}}
@@ -181,0 +194,0 @@ // export const signature = ''

test-built/dist/mjs/index.d.ts

@@ -17,3 +17,15 @@ import { PromiseWithSubtest, TapPlugin, TestBase, TestBaseOpts } from '@tapjs/core';
 import type { ConfigSet, Jack } from 'jackspeak';
+/**
+ * The set of file extensions that the tap runner will load
+ * by default. Expaned into the `include` config values if they
+ * contain the token `__EXTENSIONS__`.
+ *
+ * If plugins export a `testFileExtensions` string array, then the
+ * entries will be added to this set.
+ */
 export declare const testFileExtensions: Set<string>;
+/**
+ * Utility type to combine the array of plugins into a single combined
+ * return type.
+ */
 export type PluginResult<P extends ((t: TestBase, opts: any) => any)[]> = P extends [
@@ -23,2 +35,6 @@ infer H extends (t: TestBase, opts: any) => any,
 ] ? ReturnType<H> & PluginResult<T> : {};
+/**
+ * Utility type to get the second parameter of a function, used to
+ * get the types of all plugin options.
+ */
 export type SecondParam<T extends [any] | [any, any]> = T extends [
@@ -42,2 +58,5 @@ any,
 export type TestOpts = TestBaseOpts & PluginOpts<PluginSet>;
+/**
+ * Type that is the array of all plugin functions loaded
+ */
 export type PluginSet = [
@@ -59,2 +78,6 @@ typeof Plugin_after.plugin,
 ];
+/**
+ * The combined configuration object generated by the `config`
+ * objects exported by plugins.
+ */
 export declare const config: <C extends ConfigSet>(jack: Jack<C>) => Jack<C & import("jackspeak").ConfigSetFromMetaSet<"boolean", false, {
@@ -96,2 +119,6 @@ only: {
     invert: {
+        /**
+         * Utility type to combine the array of plugins into a single combined
+         * return type.
+         */
         type: string;
@@ -176,7 +203,17 @@ short: string;
 }>>;
+/**
+ * The set of `loader` strings exported by plugins. If a plugin exports
+ * `preload = true`, then it will be sorted to the start of this list, so
+ * that Node loads it before other loaders.
+ */
 export declare const loaders: string[];
+/**
+ * The string signature that lists all loaded plugins alphabetically, used
+ * to determine whether a rebuild is necessary by comparing it to the `plugin`
+ * config value.
+ */
 export declare const signature = "@tapjs/after\n@tapjs/after-each\n@tapjs/asserts\n@tapjs/before\n@tapjs/before-each\n@tapjs/filter\n@tapjs/fixture\n@tapjs/intercept\n@tapjs/mock\n@tapjs/snapshot\n@tapjs/spawn\n@tapjs/stdin\n@tapjs/typescript\n@tapjs/worker";
 /**
- * Union type of {@link @tapjs/core!test-base.TestBase} plus all plugin return
- * values
+ * Union of {@link @tapjs/core!test-base.TestBase} plus all plugin
+ * return values
  */
@@ -186,2 +223,5 @@ export type TTest<P extends PluginSet = PluginSet> = TestBase & PluginResult<P>;
  * Interface that is the assembled result of every loaded plugin.
+ *
+ * This is extended into an interface because otherwise the code
+ * hinting is overwhelmingly extravagant.
  */
@@ -192,2 +232,8 @@ export interface BuiltPlugins extends PluginResult<PluginSet> {
 declare const kClass: unique symbol;
+/**
+ * Option object used when extending the `Test` class via
+ * {@link @tapjs/test!index.Test.applyPlugin}
+ *
+ * @internal
+ */
 export type PluginExtensionOption<E extends BuiltPlugins = BuiltPlugins, O extends TestOpts = TestOpts> = {
@@ -194,0 +240,0 @@ [kPluginSet]: TapPlugin<any, O>[];

test-built/dist/mjs/index.js

@@ -22,2 +22,10 @@ //{{HEADER COMMENT START}}
 import { inspect } from 'node:util';
+/**
+ * The set of file extensions that the tap runner will load
+ * by default. Expaned into the `include` config values if they
+ * contain the token `__EXTENSIONS__`.
+ *
+ * If plugins export a `testFileExtensions` string array, then the
+ * entries will be added to this set.
+ */
 export const testFileExtensions = new Set(['js', 'cjs', 'mjs']);
@@ -59,11 +67,2 @@ //{{FILE TYPES START}}
 let plugins_;
-//{{PLUGINS CODE START}}
-// const plugins = () => {
-//   if (plugins_) return plugins_
-//   return (plugins_ = [])
-// }
-// export type PluginSet = (
-//   | TapPlugin<any>
-//   | TapPlugin<any, TestBaseOpts>
-// )[]
 const plugins = () => {
@@ -90,2 +89,6 @@ if (plugins_)
 //{{PLUGINS CODE END}}
+/**
+ * The combined configuration object generated by the `config`
+ * objects exported by plugins.
+ */
 //{{PLUGINS CONFIG START}}
@@ -146,2 +149,7 @@ // // just referenced to keep prettier/tslint happy
 ]);
+/**
+ * The set of `loader` strings exported by plugins. If a plugin exports
+ * `preload = true`, then it will be sorted to the start of this list, so
+ * that Node loads it before other loaders.
+ */
 export const loaders = [
@@ -152,2 +160,7 @@ "@tapjs/mock/loader",
 //{{LOADERS END}}
+/**
+ * The string signature that lists all loaded plugins alphabetically, used
+ * to determine whether a rebuild is necessary by comparing it to the `plugin`
+ * config value.
+ */
 //{{PLUGIN SIGNATURE START}}
@@ -154,0 +167,0 @@ // export const signature = ''

test-built/src/index.ts

@@ -35,2 +35,10 @@ //{{HEADER COMMENT START}}
 
+/**
+ * The set of file extensions that the tap runner will load
+ * by default. Expaned into the `include` config values if they
+ * contain the token `__EXTENSIONS__`.
+ *
+ * If plugins export a `testFileExtensions` string array, then the
+ * entries will be added to this set.
+ */
 export const testFileExtensions = new Set(['js', 'cjs', 'mjs'])
@@ -87,2 +95,6 @@ //{{FILE TYPES START}}
 
+/**
+ * Utility type to combine the array of plugins into a single combined
+ * return type.
+ */
 export type PluginResult<
@@ -97,2 +109,5 @@ P extends ((t: TestBase, opts: any) => any)[]
 
+/**
+ * The union of return types of an array of functions
+ */
 type AnyReturnValue<A extends ((...a: any[]) => any)[]> = A extends [
@@ -120,3 +135,6 @@ infer H extends (...a: any[]) => any,
 
-// options
+/**
+ * Utility type to get the second parameter of a function, used to
+ * get the types of all plugin options.
+ */
 export type SecondParam<T extends [any] | [any, any]> = T extends [
@@ -151,3 +169,10 @@ any,
 
+/**
+ * Type that is the array of all plugin functions loaded
+ */
 //{{PLUGINS CODE START}}
+// export type PluginSet = (
+//   | TapPlugin<any>
+//   | TapPlugin<any, TestBaseOpts>
+// )[]
 // const plugins = () => {
@@ -157,6 +182,19 @@ //   if (plugins_) return plugins_
 // }
-// export type PluginSet = (
-//   | TapPlugin<any>
-//   | TapPlugin<any, TestBaseOpts>
-// )[]
+export type PluginSet = [
+  typeof Plugin_after.plugin,
+  typeof Plugin_afterEach.plugin,
+  typeof Plugin_asserts.plugin,
+  typeof Plugin_before.plugin,
+  typeof Plugin_beforeEach.plugin,
+  typeof Plugin_filter.plugin,
+  typeof Plugin_fixture.plugin,
+  typeof Plugin_intercept.plugin,
+  typeof Plugin_mock.plugin,
+  typeof Plugin_snapshot.plugin,
+  typeof Plugin_spawn.plugin,
+  typeof Plugin_stdin.plugin,
+  typeof Plugin_typescript.plugin,
+  typeof Plugin_worker.plugin,
+]
+
 const plugins = () => {
@@ -181,21 +219,8 @@ if (plugins_) return plugins_
 }
-
-export type PluginSet = [
-  typeof Plugin_after.plugin,
-  typeof Plugin_afterEach.plugin,
-  typeof Plugin_asserts.plugin,
-  typeof Plugin_before.plugin,
-  typeof Plugin_beforeEach.plugin,
-  typeof Plugin_filter.plugin,
-  typeof Plugin_fixture.plugin,
-  typeof Plugin_intercept.plugin,
-  typeof Plugin_mock.plugin,
-  typeof Plugin_snapshot.plugin,
-  typeof Plugin_spawn.plugin,
-  typeof Plugin_stdin.plugin,
-  typeof Plugin_typescript.plugin,
-  typeof Plugin_worker.plugin,
-]
 //{{PLUGINS CODE END}}
 
+/**
+ * The combined configuration object generated by the `config`
+ * objects exported by plugins.
+ */
 //{{PLUGINS CONFIG START}}
@@ -258,2 +283,7 @@ // // just referenced to keep prettier/tslint happy
 
+/**
+ * The set of `loader` strings exported by plugins. If a plugin exports
+ * `preload = true`, then it will be sorted to the start of this list, so
+ * that Node loads it before other loaders.
+ */
 export const loaders: string[] = [
@@ -267,2 +297,7 @@ "@tapjs/mock/loader",
 
+/**
+ * The string signature that lists all loaded plugins alphabetically, used
+ * to determine whether a rebuild is necessary by comparing it to the `plugin`
+ * config value.
+ */
 //{{PLUGIN SIGNATURE START}}
@@ -287,4 +322,4 @@ // export const signature = ''
 /**
- * Union type of {@link @tapjs/core!test-base.TestBase} plus all plugin return
- * values
+ * Union of {@link @tapjs/core!test-base.TestBase} plus all plugin
+ * return values
  */
@@ -296,2 +331,5 @@ export type TTest<P extends PluginSet = PluginSet> = TestBase &
  * Interface that is the assembled result of every loaded plugin.
+ *
+ * This is extended into an interface because otherwise the code
+ * hinting is overwhelmingly extravagant.
  */
@@ -426,2 +464,8 @@ export interface BuiltPlugins extends PluginResult<PluginSet> {}
 const kClass = Symbol('@tapjs/test construction class')
+/**
+ * Option object used when extending the `Test` class via
+ * {@link @tapjs/test!index.Test.applyPlugin}
+ *
+ * @internal
+ */
 export type PluginExtensionOption<
@@ -428,0 +472,0 @@ E extends BuiltPlugins = BuiltPlugins,

test-built/tsconfig.json

 {
   "compilerOptions": {
+    "rootDir": "./src",
     "declaration": true,
@@ -4,0 +5,0 @@ "declarationMap": true,

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

198167

increased by6.3%

Lines of code

2959

increased by7.37%

Number of lines in readme file

99

increased by2375%

No dependency changes