@ohos-ports/jest-dev-server 0.0.0-stage → 11.0.0-beta.0

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2024 Smooth Code
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,227 @@
-# Temporary Holding Version
+# jest-dev-server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm version](https://img.shields.io/npm/v/jest-dev-server.svg)](https://www.npmjs.com/package/jest-dev-server)
+[![npm dm](https://img.shields.io/npm/dm/jest-dev-server.svg)](https://www.npmjs.com/package/jest-dev-server)
+[![npm dt](https://img.shields.io/npm/dt/jest-dev-server.svg)](https://www.npmjs.com/package/jest-dev-server)
+
+Starts a server before your Jest tests and tears it down after.
+
+## Why
+
+`jest-puppeteer` works great for running tests in Jest using Puppeteer.
+It's also useful for starting a local development server during the tests without letting Jest hang.
+This package extracts just the local development server spawning without any ties to Puppeteer.
+
+## Install
+
+```bash
+npm install --save-dev jest-dev-server
+```
+
+## Usage
+
+`jest-dev-server` exports `setup` and `teardown` functions.
+
+```js
+// global-setup.js
+const { setup: setupDevServer } = require("jest-dev-server");
+
+module.exports = async function globalSetup() {
+  globalThis.servers = await setupDevServer({
+    command: `node config/start.js --port=3000`,
+    launchTimeout: 50000,
+    port: 3000,
+  });
+  // Your global setup
+};
+```
+
+```js
+// global-teardown.js
+const { teardown: teardownDevServer } = require("jest-dev-server");
+
+module.exports = async function globalTeardown() {
+  await teardownDevServer(globalThis.servers);
+  // Your global teardown
+};
+```
+
+### Specify several servers
+
+You can specify several servers using an array of configs:
+
+```js
+// global-setup.js
+const { setup: setupDevServer } = require("jest-dev-server");
+
+module.exports = async function globalSetup() {
+  globalThis.servers = await setupDevServer([
+    {
+      command: "node server.js",
+      port: 4444,
+    },
+    {
+      command: "node server2.js",
+      port: 4445,
+    },
+  ]);
+  // Your global setup
+};
+```
+
+## Options
+
+### `command`
+
+Type: `string`, required.
+
+Command to execute to start the port.
+Directly passed to [`spawnd`](https://www.npmjs.com/package/spawnd).
+
+```js
+const options = {
+  command: "npm run start",
+};
+```
+
+### `debug`
+
+Type: `boolean`, default to `false`.
+
+Log server output, useful if server is crashing at start.
+
+```js
+const options = {
+  command: "npm run start",
+  debug: true,
+};
+```
+
+### `launchTimeout`
+
+Type: `number`, default to `5000`.
+
+How many milliseconds to wait for the spawned server to be available before giving up.
+Defaults to [`wait-port`](https://www.npmjs.com/package/wait-port)'s default.
+
+```js
+const options = {
+  command: "npm run start",
+  launchTimeout: 30000,
+};
+```
+
+---
+
+Following options are linked to [`spawnd`](https://www.npmjs.com/package/spawnd).
+
+### `host`
+
+Type: `string`, if not specified it will used Node.js default port.
+
+Host to wait for activity on before considering the server running.
+Must be used in conjunction with `port`.
+
+```js
+const options = {
+  command: "npm run start --port 3000",
+  host: "customhost.com",
+  port: 3000,
+};
+```
+
+### `path`
+
+Type: `string`, default to `null`.
+
+Path to resource to wait for activity on before considering the server running.
+Must be used in conjunction with `host` and `port`.
+
+```js
+const options = {
+  command: "npm run start --port 3000",
+  host: "customhost.com",
+  port: 3000,
+  path: "thing",
+};
+```
+
+### `protocol`
+
+Type: `string`, (`https`, `http`, `tcp`, `socket`) default to `tcp`.
+
+To wait for an HTTP or TCP endpoint before considering the server running, include `http` or `tcp` as a protocol.
+Must be used in conjunction with `port`.
+
+```js
+const options = {
+  command: "npm run start --port 3000",
+  protocol: "http",
+  port: 3000,
+};
+```
+
+### `port`
+
+Type: `number`, default to `null`.
+
+Port to wait for activity on before considering the server running.
+If not provided, the server is assumed to immediately be running.
+
+```js
+const options = {
+  command: "npm run start --port 3000",
+  port: 3000,
+};
+```
+
+### `usedPortAction`
+
+Type: `string` (`ask`, `error`, `ignore`, `kill`) default to `ask`.
+
+It defines the action to take if port is already used:
+
+- `ask`: a prompt is shown to decide if you want to kill the process or not
+- `error`: an errow is thrown
+- `ignore`: your test are executed, we assume that the server is already started
+- `kill`: the process is automatically killed without a prompt
+
+```js
+const options = {
+  command: "npm run start --port 3000",
+  port: 3000,
+  usedPortAction: "kill",
+};
+```
+
+### `waitOnScheme`
+
+`jest-dev-server` use the [`wait-on`](https://www.npmjs.com/package/wait-on) npm package to wait for resources to become available before calling callback.
+
+Type: `object`, default to `{}`.
+
+- `delay`: optional initial delay in ms, default 0
+- `interval`: optional poll resource interval in ms, default 250ms
+- `log`: optional flag which outputs to stdout, remaining resources waited on and when complete or errored
+- `reverse`: optional flag to reverse operation so checks are for resources being NOT available, default false
+- `timeout`: optional timeout in ms, default Infinity. Aborts with error
+- `tcpTimeout`: optional tcp timeout in ms, default 300ms
+- `verbose`: optional flag which outputs debug output, default false
+- `window`: optional stabilization time in ms, default 750ms. Waits this amount of time for file sizes to stabilize or other resource availability to remain unchanged
+
+**Note:** http(s) specific options, see https://github.com/request/request#readme for specific details
+
+```js
+const options = {
+  command: "npm run start --port 3000",
+  port: 3000,
+  usedPortAction: "kill",
+  waitOnScheme: {
+    delay: 1000,
+  },
+};
+```
+
+## Troubleshooting
+
+- If using `port` makes the terminal to ask for root password although the port is valid and accessible then use `usePortAction: 'ignore'`.

package/dist/index.d.ts

@@ -0,0 +1,70 @@
+import { SpawndOptions, SpawndChildProcess } from 'spawnd';
+import { WaitOnOptions } from 'wait-on';
+
+type Config = {
+    /**
+     * Command to execute to start the port.
+     * Directly passed to [`spawnd`](https://www.npmjs.com/package/spawnd).
+     * @example "npm run start"
+     * @example "yarn start"
+     * @example "node server.js"
+     * @see https://www.npmjs.com/package/spawnd#command
+     */
+    command: string;
+    /**
+     * Enable debug mode.
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * Spawnd options.
+     * @see https://www.npmjs.com/package/spawnd#options
+     */
+    options?: SpawndOptions;
+    /**
+     * Timeout to wait for the server to start.
+     * @default 5000
+     */
+    launchTimeout?: number;
+    /**
+     * Host to use to check if the port is used.
+     */
+    host?: string;
+    /**
+     * Port to use to check if the port is used.
+     */
+    port?: number;
+    /**
+     * Path to use to check if the port is used.
+     */
+    path?: string;
+    /**
+     * Protocol to use to check if the port is used.
+     * @default "tcp"
+     */
+    protocol?: "tcp" | "http" | "https" | "socket";
+    /**
+     * Action to take if the port is already used.
+     * @default "ask"
+     */
+    usedPortAction?: "ask" | "error" | "ignore" | "kill";
+    /**
+     * Options to pass to [`wait-on`](https://www.npmjs.com/package/wait-on).
+     * @see https://www.npmjs.com/package/wait-on#options
+     */
+    waitOnScheme?: WaitOnOptions;
+};
+declare const ERROR_TIMEOUT = "ERROR_TIMEOUT";
+declare const ERROR_PORT_USED = "ERROR_PORT_USED";
+declare const ERROR_NO_COMMAND = "ERROR_NO_COMMAND";
+declare class JestDevServerError extends Error {
+    code?: string;
+    constructor(message: string, options?: {
+        code?: string;
+        cause?: Error;
+    });
+}
+declare function setup(providedConfigs: Config | Config[]): Promise<SpawndChildProcess[]>;
+declare function teardown(procs: SpawndChildProcess[]): Promise<void>;
+
+export { type Config, ERROR_NO_COMMAND, ERROR_PORT_USED, ERROR_TIMEOUT, JestDevServerError, setup, teardown };

package/dist/index.js

@@ -0,0 +1,213 @@
+'use strict';
+
+var node_stream = require('node:stream');
+var node_net = require('node:net');
+var node_util = require('node:util');
+var chalk = require('chalk');
+var spawnd = require('spawnd');
+var cwd = require('cwd');
+var waitOn = require('wait-on');
+var findProcess = require('find-process');
+var treeKill = require('@ohos-ports/tree-kill');
+var prompts = require('prompts');
+
+const DEFAULT_CONFIG = {
+    debug: false,
+    options: {},
+    launchTimeout: 5000,
+    host: undefined,
+    port: undefined,
+    protocol: "tcp",
+    usedPortAction: "ask",
+    waitOnScheme: undefined
+};
+const resolveConfig = (config)=>{
+    return {
+        ...DEFAULT_CONFIG,
+        ...config
+    };
+};
+const pTreeKill = node_util.promisify(treeKill);
+const serverLogPrefixer = new node_stream.Transform({
+    transform (chunk, _encoding, callback) {
+        this.push(chalk.magentaBright(`[jest-dev-server] ${chunk.toString()}`));
+        callback();
+    }
+});
+const ERROR_TIMEOUT = "ERROR_TIMEOUT";
+const ERROR_PORT_USED = "ERROR_PORT_USED";
+const ERROR_NO_COMMAND = "ERROR_NO_COMMAND";
+class JestDevServerError extends Error {
+    code;
+    constructor(message, options){
+        // @ts-ignore - cause is not part of the Error constructor (yet)
+        super(message, options?.cause ? {
+            cause: options.cause
+        } : undefined);
+        this.code = options?.code;
+    }
+}
+const logProcDetection = (name, port)=>{
+    console.log(chalk.blue(`🕵️  Detecting a process "${name}" running on port "${port}"`));
+};
+const killProc = async (proc)=>{
+    console.log(chalk.yellow(`Killing process ${proc.name}...`));
+    await pTreeKill(proc.pid);
+    console.log(chalk.green(`Successfully killed process ${proc.name}`));
+};
+const spawnServer = (config)=>{
+    if (!config.command) {
+        throw new JestDevServerError("You must define a `command`", {
+            code: ERROR_NO_COMMAND
+        });
+    }
+    const proc = spawnd.spawnd(config.command, {
+        shell: true,
+        env: process.env,
+        cwd: cwd(),
+        ...config.options
+    });
+    if (config.debug) {
+        console.log(chalk.magentaBright("\nJest dev-server output:"));
+        proc.stdout.pipe(serverLogPrefixer).pipe(process.stdout);
+    } else {
+        // eslint-disable-next-line @typescript-eslint/no-empty-function
+        proc.stdout.on("data", ()=>{});
+    }
+    return proc;
+};
+const outOfStin = async (run)=>{
+    const { stdin } = process;
+    const listeners = stdin.listeners("data");
+    const result = await run();
+    // @ts-ignore
+    listeners.forEach((listener)=>stdin.on("data", listener));
+    stdin.setRawMode(true);
+    stdin.setEncoding("utf8");
+    stdin.resume();
+    return result;
+};
+const checkIsPortBusy = async (config)=>{
+    return new Promise((resolve)=>{
+        const server = node_net.createServer().once("error", (err)=>{
+            if (err.code === "EADDRINUSE") {
+                resolve(true);
+            } else {
+                resolve(false);
+            }
+        }).once("listening", ()=>{
+            server.once("close", ()=>resolve(false)).close();
+        }).listen(config.port, config.host);
+    });
+};
+const usedPortHandlers = {
+    error: (port)=>{
+        throw new JestDevServerError(`Port ${port} is in use`, {
+            code: ERROR_PORT_USED
+        });
+    },
+    kill: async (port)=>{
+        console.log("");
+        console.log(`Killing process listening to ${port}. On linux, this may require you to enter your password.`);
+        const [portProcess] = await findProcess("port", port);
+        logProcDetection(portProcess.name, port);
+        await killProc(portProcess);
+        return true;
+    },
+    ask: async (port)=>{
+        console.log("");
+        const answers = await outOfStin(()=>prompts({
+                type: "confirm",
+                name: "kill",
+                message: `Another process is listening on ${port}. Should I kill it for you? On linux, this may require you to enter your password.`,
+                initial: true
+            }));
+        if (answers.kill) {
+            const [portProcess] = await findProcess("port", port);
+            logProcDetection(portProcess.name, port);
+            await killProc(portProcess);
+            return true;
+        }
+        process.exit(1);
+    },
+    ignore: (port)=>{
+        console.log("");
+        console.log(`Port ${port} is already used. Assuming server is already running.`);
+        return false;
+    }
+};
+const handleUsedPort = async (config)=>{
+    if (config.port === undefined) return true;
+    if (!config.usedPortAction) {
+        throw new JestDevServerError(`Port ${config.port} is in use, but no action was provided to handle it. Please provide a "usedPortAction" in your config.`);
+    }
+    const isPortBusy = await checkIsPortBusy(config);
+    if (isPortBusy) {
+        const usedPortHandler = usedPortHandlers[config.usedPortAction];
+        return await usedPortHandler(config.port);
+    }
+    return true;
+};
+const checkIsTimeoutError = (err)=>{
+    return Boolean(err?.message?.startsWith("Timed out waiting for"));
+};
+const waitForServerToBeReady = async (config)=>{
+    if (config.port === undefined) return;
+    const { launchTimeout, protocol, host, port, path, waitOnScheme } = config;
+    let resource = `${host ?? "0.0.0.0"}:${port}`;
+    if (path) {
+        resource = `${resource}/${path}`;
+    }
+    let url;
+    if (protocol === "tcp" || protocol === "socket") {
+        url = `${protocol}:${resource}`;
+    } else {
+        url = `${protocol}://${resource}`;
+    }
+    const opts = {
+        resources: [
+            url
+        ],
+        timeout: launchTimeout,
+        ...waitOnScheme
+    };
+    try {
+        await waitOn(opts);
+    } catch (err) {
+        if (checkIsTimeoutError(err)) {
+            throw new JestDevServerError(`Server has taken more than ${launchTimeout}ms to start.`, {
+                code: ERROR_TIMEOUT
+            });
+        }
+        throw err;
+    }
+};
+const setupJestServer = async (providedConfig)=>{
+    const config = resolveConfig(providedConfig);
+    const shouldRunServer = await handleUsedPort(config);
+    if (shouldRunServer) {
+        const proc = spawnServer(config);
+        await waitForServerToBeReady(config);
+        return proc;
+    }
+    return null;
+};
+async function setup(providedConfigs) {
+    const configs = Array.isArray(providedConfigs) ? providedConfigs : [
+        providedConfigs
+    ];
+    const procs = await Promise.all(configs.map((config)=>setupJestServer(config)));
+    return procs.filter(Boolean);
+}
+async function teardown(procs) {
+    if (procs.length) {
+        await Promise.all(procs.map((proc)=>proc.destroy()));
+    }
+}
+
+exports.ERROR_NO_COMMAND = ERROR_NO_COMMAND;
+exports.ERROR_PORT_USED = ERROR_PORT_USED;
+exports.ERROR_TIMEOUT = ERROR_TIMEOUT;
+exports.JestDevServerError = JestDevServerError;
+exports.setup = setup;
+exports.teardown = teardown;

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@ohos-ports/jest-dev-server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "description": "Starts a server before your Jest tests and tears it down after.",
+  "version": "11.0.0-beta.0",
+  "type": "commonjs",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ohos-ports/ohos-ports.git",
+    "directory": "ports/jest-dev-server/11.0.0"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/argos-ci/jest-puppeteer/tree/main/packages/jest-dev-server#readme",
+  "bugs": {
+    "url": "https://github.com/argos-ci/jest-puppeteer/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "jest",
+    "jest-environment",
+    "server"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "prebuild": "rm -rf dist",
+    "build": "rollup -c"
+  },
+  "devDependencies": {
+    "@types/cwd": "^0.10.2",
+    "@types/prompts": "^2.4.9",
+    "@types/wait-on": "^5.3.4",
+    "@ohos-ports/rollup": "^4.62.2-beta.2",
+    "rollup-plugin-dts": "^6.1.1",
+    "@ohos-ports/rollup-plugin-swc3": "^0.12.1-beta.1"
+  },
+  "dependencies": {
+    "chalk": "^4.1.2",
+    "cwd": "^0.10.0",
+    "find-process": "^1.4.7",
+    "prompts": "^2.4.2",
+    "spawnd": "^11.0.0",
+    "@ohos-ports/tree-kill": "^1.2.2-beta.0",
+    "wait-on": "^8.0.1"
+  },
+  "gitHead": "ddb3fb9d80b2d38d27b327c0d857280edf877f3e"
+}