@effectionx/test-adapter 0.1.1

package/README.md

@@ -0,0 +1,38 @@
+# Test Adapter
+
+An abstract helper for integrating Effection with testing frameworks.
+
+---
+
+Typically, you won't use this module directly, but instead you'll use one of the
+actual testing framework integrations. The following shows how you might
+integrate it with the `@std/bdd` module. You would never use it this way, this
+demonstrates the general pattern of lifecycle.
+
+```ts
+import { run, sleep } from "effection";
+import { createTestAdapter, TestAdapter } from "@effectionx/test-adapter";
+import { describe, it, beforeEach } from "@std/bdd";
+
+
+describe("something", () => {
+  let adapter: TestAdapter;
+  beforeAll(() => {)
+    adapter = createTestAdapter("something");
+  });
+  
+  afterAll(() => adapter.destroy())
+  
+  adapter.addSetup(function*() {
+    /* do some setup. equivalent of beforeEach() */
+	/* contexts set here will be visible in the test */*
+  });
+  
+  it("does a thing", async () => {
+    await adapter.runTest(function*() {
+	  /* ... the body of the test */
+	});
+  });
+
+});
+```

package/esm/mod.d.ts

@@ -0,0 +1,68 @@
+import type { Future, Operation, Scope } from "effection";
+export interface TestOperation {
+    (): Operation<void>;
+}
+export interface TestAdapter {
+    /**
+     * The parent of this adapter. All of the setup from this adapter will be
+     * run in addition to the setup of this adapter during `runTest()`
+     */
+    readonly parent?: TestAdapter;
+    /**
+     * The name of this adapter which is mostly useful for debugging purposes
+     */
+    readonly name: string;
+    /**
+     * A qualified name that contains not only the name of this adapter, but of all its
+     * ancestors. E.g. `All Tests > File System > write`
+     */
+    readonly fullname: string;
+    /**
+     * Every test adapter has its own Effection `Scope` which holds the resources necessary
+     * to run this test.
+     */
+    readonly scope: Scope;
+    /**
+     * A list of this test adapter and every adapter that it descends from.
+     */
+    readonly lineage: Array<TestAdapter>;
+    /**
+     * The setup operations that will be run by this test adapter. It only includes those
+     * setups that are associated with this adapter, not those of its ancestors.
+     */
+    readonly setups: TestOperation[];
+    /**
+     * Add a setup operation to every test that is part of this adapter. In BDD integrations,
+     * this is usually called by `beforEach()`
+     */
+    addSetup(op: TestOperation): void;
+    /**
+     * Actually run a test. This evaluates all setup operations, and then after those have completed
+     * it runs the body of the test itself.
+     */
+    runTest(body: TestOperation): Future<void>;
+    /**
+     * Teardown this test adapter and all of the task and resources that are running inside it.
+     * This basically destroys the Effection `Scope` associated with this adapter.
+     */
+    destroy(): Future<void>;
+}
+export interface TestAdapterOptions {
+    /**
+     * The name of this test adapter which is handy for debugging.
+     * Usually, you'll give this the same name as the current test
+     * context. For example, when integrating with BDD, this would be
+     * the same as
+     */
+    name?: string;
+    /**
+     * The parent test adapter. All of the setup from this adapter will be
+     * run in addition to the setup of this adapter during `runTest()`
+     */
+    parent?: TestAdapter;
+}
+/**
+ * Create a new test adapter with the given options.
+ */
+export declare function createTestAdapter(options?: TestAdapterOptions): TestAdapter;
+//# sourceMappingURL=mod.d.ts.map

package/esm/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../src/mod.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AAG1D,MAAM,WAAW,aAAa;IAC5B,IAAI,SAAS,CAAC,IAAI,CAAC,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAE9B;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IAEtB;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC;IAErC;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,aAAa,EAAE,CAAC;IAEjC;;;OAGG;IACH,QAAQ,CAAC,EAAE,EAAE,aAAa,GAAG,IAAI,CAAC;IAElC;;;OAGG;IACH,OAAO,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;IAE3C;;;OAGG;IACH,OAAO,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC;CACzB;AAED,MAAM,WAAW,kBAAkB;IACjC;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AASD;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,GAAE,kBAAuB,GAC/B,WAAW,CAwCb"}

package/esm/mod.js

@@ -0,0 +1,45 @@
+import { createScope } from "effection";
+const anonymousNames = (function* () {
+    let count = 1;
+    while (true) {
+        yield `anonymous test adapter ${count++}`;
+    }
+})();
+/**
+ * Create a new test adapter with the given options.
+ */
+export function createTestAdapter(options = {}) {
+    let setups = [];
+    let { parent, name = anonymousNames.next().value } = options;
+    let [scope, destroy] = createScope(parent?.scope);
+    let adapter = {
+        parent,
+        name,
+        scope,
+        setups,
+        get lineage() {
+            let lineage = [adapter];
+            for (let current = parent; current; current = current.parent) {
+                lineage.unshift(current);
+            }
+            return lineage;
+        },
+        get fullname() {
+            return adapter.lineage.map((adapter) => adapter.name).join(" > ");
+        },
+        addSetup(op) {
+            setups.push(op);
+        },
+        runTest(op) {
+            return scope.run(function* () {
+                let allSetups = adapter.lineage.reduce((all, adapter) => all.concat(adapter.setups), []);
+                for (let setup of allSetups) {
+                    yield* setup();
+                }
+                yield* op();
+            });
+        },
+        destroy,
+    };
+    return adapter;
+}

package/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@effectionx/test-adapter",
+  "version": "0.1.1",
+  "author": "engineering@frontside.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thefrontside/effectionx.git"
+  },
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/thefrontside/effectionx/issues"
+  },
+  "main": "./script/mod.js",
+  "module": "./esm/mod.js",
+  "exports": {
+    ".": {
+      "import": "./esm/mod.js",
+      "require": "./script/mod.js"
+    }
+  },
+  "engines": {
+    "node": ">= 16"
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "effection": "4.0.0-alpha.5"
+  },
+  "_generatedBy": "dnt@dev"
+}

package/script/mod.d.ts

@@ -0,0 +1,68 @@
+import type { Future, Operation, Scope } from "effection";
+export interface TestOperation {
+    (): Operation<void>;
+}
+export interface TestAdapter {
+    /**
+     * The parent of this adapter. All of the setup from this adapter will be
+     * run in addition to the setup of this adapter during `runTest()`
+     */
+    readonly parent?: TestAdapter;
+    /**
+     * The name of this adapter which is mostly useful for debugging purposes
+     */
+    readonly name: string;
+    /**
+     * A qualified name that contains not only the name of this adapter, but of all its
+     * ancestors. E.g. `All Tests > File System > write`
+     */
+    readonly fullname: string;
+    /**
+     * Every test adapter has its own Effection `Scope` which holds the resources necessary
+     * to run this test.
+     */
+    readonly scope: Scope;
+    /**
+     * A list of this test adapter and every adapter that it descends from.
+     */
+    readonly lineage: Array<TestAdapter>;
+    /**
+     * The setup operations that will be run by this test adapter. It only includes those
+     * setups that are associated with this adapter, not those of its ancestors.
+     */
+    readonly setups: TestOperation[];
+    /**
+     * Add a setup operation to every test that is part of this adapter. In BDD integrations,
+     * this is usually called by `beforEach()`
+     */
+    addSetup(op: TestOperation): void;
+    /**
+     * Actually run a test. This evaluates all setup operations, and then after those have completed
+     * it runs the body of the test itself.
+     */
+    runTest(body: TestOperation): Future<void>;
+    /**
+     * Teardown this test adapter and all of the task and resources that are running inside it.
+     * This basically destroys the Effection `Scope` associated with this adapter.
+     */
+    destroy(): Future<void>;
+}
+export interface TestAdapterOptions {
+    /**
+     * The name of this test adapter which is handy for debugging.
+     * Usually, you'll give this the same name as the current test
+     * context. For example, when integrating with BDD, this would be
+     * the same as
+     */
+    name?: string;
+    /**
+     * The parent test adapter. All of the setup from this adapter will be
+     * run in addition to the setup of this adapter during `runTest()`
+     */
+    parent?: TestAdapter;
+}
+/**
+ * Create a new test adapter with the given options.
+ */
+export declare function createTestAdapter(options?: TestAdapterOptions): TestAdapter;
+//# sourceMappingURL=mod.d.ts.map

package/script/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../src/mod.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AAG1D,MAAM,WAAW,aAAa;IAC5B,IAAI,SAAS,CAAC,IAAI,CAAC,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAE9B;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IAEtB;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC;IAErC;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,aAAa,EAAE,CAAC;IAEjC;;;OAGG;IACH,QAAQ,CAAC,EAAE,EAAE,aAAa,GAAG,IAAI,CAAC;IAElC;;;OAGG;IACH,OAAO,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;IAE3C;;;OAGG;IACH,OAAO,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC;CACzB;AAED,MAAM,WAAW,kBAAkB;IACjC;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AASD;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,GAAE,kBAAuB,GAC/B,WAAW,CAwCb"}

package/script/mod.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTestAdapter = createTestAdapter;
+const effection_1 = require("effection");
+const anonymousNames = (function* () {
+    let count = 1;
+    while (true) {
+        yield `anonymous test adapter ${count++}`;
+    }
+})();
+/**
+ * Create a new test adapter with the given options.
+ */
+function createTestAdapter(options = {}) {
+    let setups = [];
+    let { parent, name = anonymousNames.next().value } = options;
+    let [scope, destroy] = (0, effection_1.createScope)(parent?.scope);
+    let adapter = {
+        parent,
+        name,
+        scope,
+        setups,
+        get lineage() {
+            let lineage = [adapter];
+            for (let current = parent; current; current = current.parent) {
+                lineage.unshift(current);
+            }
+            return lineage;
+        },
+        get fullname() {
+            return adapter.lineage.map((adapter) => adapter.name).join(" > ");
+        },
+        addSetup(op) {
+            setups.push(op);
+        },
+        runTest(op) {
+            return scope.run(function* () {
+                let allSetups = adapter.lineage.reduce((all, adapter) => all.concat(adapter.setups), []);
+                for (let setup of allSetups) {
+                    yield* setup();
+                }
+                yield* op();
+            });
+        },
+        destroy,
+    };
+    return adapter;
+}

package/script/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}