@warp-drive/holodeck 0.0.0-alpha.84 → 0.0.0-alpha.86

package/README.md

@@ -94,6 +94,152 @@ and `brotli` minification in a way that can be replayed over and over again.
 
 Basically, pay the cost when you write the test. Forever after skip the cost until you need to edit the test again.
 
+## Setup
+
+### Use with WarpDrive
+
+First, you will need to add the holodeck handler to the request manager chain prior to `Fetch` (or any equivalent handler that proceeds to network).
+
+For instance:
+
+```ts
+import RequestManager from '@ember-data/request';
+import Fetch from '@ember-data/request/fetch';
+import { MockServerHandler } from '@warp-drive/holodeck';
+
+const manager = new RequestManager();
+manager.use([new MockServerHandler(testContext), Fetch]);
+```
+
+From within a test this might look like:
+
+```ts
+import RequestManager from '@ember-data/request';
+import Fetch from '@ember-data/request/fetch';
+import { MockServerHandler } from '@warp-drive/holodeck';
+import { module, test } from 'qunit';
+
+module('my module', function() {
+  test('my test', async function() {
+    const manager = new RequestManager();
+    manager.use([new MockServerHandler(this), Fetch]);
+  });
+});
+```
+
+Next, you will need to configure holodeck to understand your tests contexts. For qunit and diagnostic
+in a project using Ember this is typically done in `tests/test-helper.js`
+
+#### With Diagnostic
+
+```ts
+import { setupGlobalHooks } from '@warp-drive/diagnostic';
+import { setConfig, setTestId } from '@warp-drive/holodeck';
+
+// if not proxying the port / set port to the correct value here
+const MockHost = `https://${window.location.hostname}:${Number(window.location.port) + 1}`;
+
+setConfig({ host: MockHost });
+
+setupGlobalHooks((hooks) => {
+  hooks.beforeEach(function (assert) {
+    setTestId(this, assert.test.testId);
+  });
+  hooks.afterEach(function () {
+    setTestId(this, null);
+  });
+});
+```
+
+#### With QUnit
+
+```ts
+import * as QUnit from 'qunit';
+import { setConfig, setTestId } from '@warp-drive/holodeck';
+
+// if not proxying the port / set port to the correct value here
+const MockHost = `https://${window.location.hostname}:${Number(window.location.port) + 1}`;
+
+setConfig({ host: MockHost });
+
+QUnit.hooks.beforeEach(function (assert) {
+  setTestId(assert.test.testId);
+});
+QUnit.hooks.afterEach(function (assert) {
+  setTestId(null);
+});
+```
+
+### Testem
+
+You can integrate holodeck with Testem using testem's [async config capability](https://github.com/testem/testem/blob/master/docs/config_file.md#returning-a-promise-from-testemjs):
+
+```ts
+module.exports = async function () {
+  const holodeck = (await import('@warp-drive/holodeck')).default;
+  await holodeck.launchProgram({
+    port: 7373,
+  });
+
+  process.on('beforeExit', async () => {
+    await holodeck.endProgram();
+  });
+
+  return {
+    // ... testem config
+  };
+};
+```
+
+If you need the API mock to run on the same port as the test suite, you can use Testem's [API Proxy](https://github.com/testem/testem/tree/master?tab=readme-ov-file#api-proxy)
+
+```ts
+module.exports = async function () {
+  const holodeck = (await import('@warp-drive/holodeck')).default;
+  await holodeck.launchProgram({
+    port: 7373,
+  });
+
+  process.on('beforeExit', async () => {
+    await holodeck.endProgram();
+  });
+
+  return {
+    "proxies": {
+      "/api": {
+        // holodeck always runs on https
+        // the proxy is transparent so this means /api/v1 will route to https://localhost:7373/api/v1
+        "target": "https://localhost:7373",
+        // "onlyContentTypes": ["xml", "json"],
+        // if test suite is on http, set this to false
+        // "secure": false,
+      },
+    }
+  };
+};
+```
+
+### Diagnostic
+
+holodeck can be launched and cleaned up using the lifecycle hooks in the launch config
+for diagnostic in `diagnostic.js`:
+
+```ts
+import launch from '@warp-drive/diagnostic/server/default-setup.js';
+import holodeck from '@warp-drive/holodeck';
+
+await launch({
+  async setup(options) {
+    await holodeck.launchProgram({
+      port: options.port + 1,
+    });
+  },
+  async cleanup() {
+    await holodeck.endProgram();
+  },
+});
+```
+
 ### ♥️ Credits
 
  <details>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@warp-drive/holodeck",
   "description": "⚡️ Simple, Fast HTTP Mocking for Tests",
-  "version": "0.0.0-alpha.84",
+  "version": "0.0.0-alpha.86",
   "license": "MIT",
   "author": "Chris Thoburn <runspired@users.noreply.github.com>",
   "repository": {
@@ -44,8 +44,8 @@
     "sync-hardlinks": "bun run sync-dependencies-meta-injected"
   },
   "peerDependencies": {
-    "@ember-data/request": "5.4.0-alpha.98",
-    "@warp-drive/core-types": "0.0.0-alpha.84"
+    "@ember-data/request": "5.4.0-alpha.100",
+    "@warp-drive/core-types": "0.0.0-alpha.86"
   },
   "devDependencies": {
     "@babel/core": "^7.24.5",
@@ -53,9 +53,9 @@
     "@babel/preset-env": "^7.24.5",
     "@babel/preset-typescript": "^7.24.1",
     "@babel/runtime": "^7.24.5",
-    "@ember-data/request": "5.4.0-alpha.98",
-    "@warp-drive/core-types": "0.0.0-alpha.84",
-    "@warp-drive/internal-config": "5.4.0-alpha.98",
+    "@ember-data/request": "5.4.0-alpha.100",
+    "@warp-drive/core-types": "0.0.0-alpha.86",
+    "@warp-drive/internal-config": "5.4.0-alpha.100",
     "pnpm-sync-dependencies-meta-injected": "0.0.14",
     "typescript": "^5.4.5",
     "vite": "^5.2.11"