@atomicsmash/init-testing 1.0.0-beta.0

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+import { readFile, writeFile, readdir, appendFile } from "node:fs/promises";
+import { dirname as pathDirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+import { PackageManager } from "./utils.js";
+// eslint-disable-next-line @typescript-eslint/naming-convention
+const __filename = fileURLToPath(import.meta.url);
+// eslint-disable-next-line @typescript-eslint/naming-convention
+const __dirname = pathDirname(__filename);
+const packageManager = new PackageManager(await import(`${process.cwd()}/package.json`).catch(() => {
+    throw new Error("Unable to find package.json in your cwd. Make sure you're running this command in the right folder.");
+}), await import(`${process.cwd()}/package-lock.json`).catch(() => {
+    throw new Error("Unable to find package-lock.json in your cwd. Make sure you're running this command in the right folder.");
+}));
+const argv = await yargs(hideBin(process.argv))
+    .options({
+    "base-url": {
+        demandOption: true,
+        describe: "Base URL to use in actions like `await page.goto('/')`",
+        type: "string",
+    },
+    "no-example": {
+        boolean: true,
+        default: false,
+        describe: "If present, don't copy over the playwright example tests.",
+    },
+    "no-universal": {
+        boolean: true,
+        default: false,
+        describe: "If present, don't copy over the Atomic Smash universal tests (NOT RECOMMENDED).",
+    },
+})
+    .showHelpOnFail(false, "Specify --help for available options")
+    .parse();
+const fileCopies = [];
+const copyFiles = await readdir(`${__dirname}/../toCopy`, {
+    withFileTypes: true,
+    recursive: true,
+});
+for (const dirent of copyFiles) {
+    console.log({ name: dirent.name, path: dirent.path });
+    if (!dirent.isFile()) {
+        continue;
+    }
+    if (argv.noExample && dirent.name === "example.spec.ts") {
+        continue;
+    }
+    if (argv.noUniversal && dirent.name === "universal.spec.ts") {
+        continue;
+    }
+    fileCopies.push(readFile(dirent.path, "utf8")
+        .then(async (data) => {
+        for (const [search, replace] of [
+            ["%%BASE_URL%%", argv.baseUrl],
+        ]) {
+            data = data.replace(search, replace);
+        }
+        await writeFile(dirent.path, data, "utf8");
+        return `${dirent.name} copied successfully.`;
+    })
+        .catch((error) => `${dirent.name} failed to copy. Error: ${error}`));
+}
+await Promise.all([
+    Promise.allSettled([
+        packageManager.ensurePackageIsInstalled("@atomicsmash/test-utils", {
+            packageConstraint: "^1.0.0",
+            type: "dev",
+        }),
+        packageManager.ensurePackageIsInstalled("@playwright/test", {
+            packageConstraint: "^1.0.0",
+            type: "dev",
+        }),
+        packageManager.ensurePackageIsInstalled("close-with-grace", {
+            packageConstraint: "^1.0.0",
+            type: "dev",
+        }),
+        packageManager.ensurePackageIsInstalled("msw", {
+            packageConstraint: "^2.0.0",
+            type: "dev",
+        }),
+        packageManager.ensurePackageIsInstalled("cross-env", {
+            packageConstraint: "^7.0.0",
+            type: "dev",
+        }),
+        async () => {
+            const [major, minor] = process.versions.node.split(".");
+            return packageManager.ensurePackageIsInstalled("@types/node", {
+                packageConstraint: `${major}.${minor}.x`,
+                type: "dev",
+            });
+        },
+    ]).then((results) => {
+        if (results.some((result) => {
+            return result.status === "fulfilled" && result.value === true;
+        })) {
+            packageManager.runCommands();
+        }
+    }),
+    Promise.allSettled(fileCopies).then((results) => {
+        results.forEach((result) => {
+            console.log(result.status === "fulfilled" ? result.value : result.reason);
+        });
+    }),
+    appendFile(`${process.cwd()}/.gitignore`, `
+
+# Testing tools
+/test-results/
+/playwright-report/
+/blob-report/
+/playwright/.cache/
+`),
+]);

package/dist/utils.d.ts

@@ -0,0 +1,51 @@
+export declare class PackageManager {
+    private packageJson;
+    private packageLockJson;
+    commands: {
+        /**
+         * Basic commands, each entry must be its own command.
+         */
+        basic: string[];
+        /**
+         * Packages to install as normal dependencies with their version constraints.
+         */
+        install: string[];
+        /**
+         * Packages to install as dev dependencies with their version constraints.
+         */
+        devInstall: string[];
+    };
+    constructor(packageJson: unknown, packageLockJson: unknown);
+    /**
+     * Run all the queued commands and then clear the commands object.
+     */
+    runCommands(): void;
+    /**
+     * Get information about the package if it's installed.
+     * @param packageName The package name of the package to get info for.
+     * @returns Various information about the package if installed, null if not installed.
+     */
+    getDependencyInfo(packageName: string): {
+        type: "normal";
+        packageConstraint: string;
+        currentVersion: string;
+    } | {
+        type: "dev";
+        packageConstraint: string;
+        currentVersion: string;
+    } | null;
+    /**
+     * This method will check if a dependency is installed, and if it isn't, it will add a command to the commands property.
+     * @param packageName The package name of the package to check.
+     * @param options (Optional) Options for installing the package.
+     * @param options.packageConstraint (Optional) What version of the package to install. Defaults to `"*"`.
+     * @param options.type (Optional) What type of dependency to install it as. Accepts `"normal"` or `"dev"`. Defaults to `"normal"`.
+     * @returns Whether a command was added to the commands prompt.
+     * @throws If the package cannot be installed.
+     */
+    ensurePackageIsInstalled(packageName: string, options?: {
+        packageConstraint?: string;
+        type?: "normal" | "dev";
+    }): Promise<boolean>;
+}
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAqBA,qBAAa,cAAc;IAC1B,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,eAAe,CAAkB;IACzC,QAAQ;QACP;;WAEG;;QAEH;;WAEG;;QAEH;;WAEG;;MAEF;gBAEU,WAAW,EAAE,OAAO,EAAE,eAAe,EAAE,OAAO;IAK1D;;OAEG;IACH,WAAW;IAaX;;;;OAIG;IACH,iBAAiB,CAAC,WAAW,EAAE,MAAM;;;;;;;;;IA2BrC;;;;;;;;OAQG;IACG,wBAAwB,CAC7B,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE;QACT,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B,IAAI,CAAC,EAAE,QAAQ,GAAG,KAAK,CAAC;KACxB;CA8FF"}

package/dist/utils.js

@@ -0,0 +1,130 @@
+import { exec } from "node:child_process";
+import { gtr as greaterThanRange, ltr as lessThanRange, validRange, } from "semver";
+export class PackageManager {
+    packageJson;
+    packageLockJson;
+    commands = {
+        /**
+         * Basic commands, each entry must be its own command.
+         */
+        basic: [],
+        /**
+         * Packages to install as normal dependencies with their version constraints.
+         */
+        install: [],
+        /**
+         * Packages to install as dev dependencies with their version constraints.
+         */
+        devInstall: [],
+    };
+    constructor(packageJson, packageLockJson) {
+        this.packageJson = packageJson;
+        this.packageLockJson = packageLockJson;
+    }
+    /**
+     * Run all the queued commands and then clear the commands object.
+     */
+    runCommands() {
+        for (const basicCommand of this.commands.basic) {
+            exec(basicCommand);
+        }
+        exec(`npm install --save ${this.commands.install.join(" ")}`);
+        exec(`npm install --save-dev ${this.commands.devInstall.join(" ")}`);
+        this.commands = {
+            basic: [],
+            install: [],
+            devInstall: [],
+        };
+    }
+    /**
+     * Get information about the package if it's installed.
+     * @param packageName The package name of the package to get info for.
+     * @returns Various information about the package if installed, null if not installed.
+     */
+    getDependencyInfo(packageName) {
+        if (this.packageJson.dependencies &&
+            packageName in this.packageJson.dependencies) {
+            return {
+                type: "normal",
+                packageConstraint: this.packageJson.dependencies[packageName] ?? "",
+                currentVersion: this.packageLockJson.packages[`node_modules/${packageName}`]
+                    ?.version ?? "",
+            };
+        }
+        if (this.packageJson.devDependencies &&
+            packageName in this.packageJson.devDependencies) {
+            return {
+                type: "dev",
+                packageConstraint: this.packageJson.devDependencies[packageName] ?? "",
+                currentVersion: this.packageLockJson.packages[`node_modules/${packageName}`]
+                    ?.version ?? "",
+            };
+        }
+        return null;
+    }
+    /**
+     * This method will check if a dependency is installed, and if it isn't, it will add a command to the commands property.
+     * @param packageName The package name of the package to check.
+     * @param options (Optional) Options for installing the package.
+     * @param options.packageConstraint (Optional) What version of the package to install. Defaults to `"*"`.
+     * @param options.type (Optional) What type of dependency to install it as. Accepts `"normal"` or `"dev"`. Defaults to `"normal"`.
+     * @returns Whether a command was added to the commands prompt.
+     * @throws If the package cannot be installed.
+     */
+    async ensurePackageIsInstalled(packageName, options) {
+        return new Promise((resolve, reject) => {
+            const { packageConstraint, type } = {
+                type: "normal",
+                packageConstraint: "*",
+                ...options,
+            };
+            const packageConstraintRange = validRange(packageConstraint);
+            if (packageConstraintRange === null) {
+                throw new Error("The packageConstraint value you entered is not a valid semver range.");
+            }
+            const dependencyInfo = this.getDependencyInfo(packageName);
+            if (type === "dev") {
+                if (dependencyInfo === null) {
+                    console.log(`${packageName} is missing, we will automatically install it for you.`);
+                    this.commands.devInstall.push(`${packageName}@${packageConstraintRange}`);
+                    return resolve(true);
+                }
+                if (greaterThanRange(dependencyInfo.currentVersion, packageConstraintRange)) {
+                    console.log(`The package ${packageName} is already installed and is newer than the requested version. You may encounter issues with your testing setup.`);
+                    return reject("NEWER_PACKAGE_FOUND");
+                }
+                if (lessThanRange(dependencyInfo.currentVersion, packageConstraintRange)) {
+                    console.log(`The package ${packageName} is already installed and is older than the requested version. You should manually update the package to match the range: ${packageConstraintRange}.`);
+                    return reject("OLDER_PACKAGE_FOUND");
+                }
+                console.log(`An acceptable version of ${packageName} is already installed, skipping...`);
+                return resolve(false);
+            }
+            if (dependencyInfo === null) {
+                console.log(`${packageName} is missing, we will automatically install it for you.`);
+                this.commands.install.push(`${packageName}@${packageConstraintRange}`);
+                return resolve(true);
+            }
+            const isFoundAsDevDependency = dependencyInfo.type === "dev";
+            if (greaterThanRange(dependencyInfo.currentVersion, packageConstraintRange)) {
+                console.log(`The package ${packageName} is already installed and is newer than the requested version. You may encounter issues with your testing setup.${isFoundAsDevDependency
+                    ? ` You should also move this dependency to be a normal dependency.`
+                    : ""}`);
+                return reject("NEWER_PACKAGE_FOUND");
+            }
+            if (lessThanRange(dependencyInfo.currentVersion, packageConstraintRange)) {
+                console.log(`The package ${packageName} is already installed and is older than the requested version. You should manually update the package to match the range: ${packageConstraintRange}.${isFoundAsDevDependency
+                    ? ` You should also move this dependency to be a normal dependency.`
+                    : ""}`);
+                return reject("OLDER_PACKAGE_FOUND");
+            }
+            if (isFoundAsDevDependency) {
+                console.log(`An acceptable version of ${packageName} is already installed, updating it to a normal dependency...`);
+                this.commands.install.push(`${packageName}@${packageConstraintRange}`);
+                return resolve(true);
+            }
+            console.log(`An acceptable version of ${packageName} is already installed, skipping...`);
+            return resolve(false);
+        });
+    }
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+	"name": "@atomicsmash/init-testing",
+	"type": "module",
+	"version": "1.0.0-beta.0",
+	"description": "Allow us to easily add automated testing setup to any npm setup.",
+	"keywords": [
+		"atomic",
+		"smash",
+		"automated testing",
+		"test",
+		"testing"
+	],
+	"homepage": "https://www.atomicsmash.co.uk/",
+	"license": "GPL-3.0-or-later",
+	"author": {
+		"name": "Atomic Smash",
+		"email": "npm@atomicsmash.co.uk",
+		"url": "https://www.atomicsmash.co.uk/"
+	},
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/AtomicSmash/packages",
+		"directory": "packages/init-testing"
+	},
+	"files": [
+		"./dist/**/*",
+		"./toCopy/**/*"
+	],
+	"bin": "./dist/cli.js",
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"dev": "tsc --build --watch tsconfig.build.json",
+		"build": "npm-run-all clean compile",
+		"clean": "del-cli ./dist/ *.tsbuildinfo",
+		"compile": "tsc --build tsconfig.build.json",
+		"test": "TZ=\"Europe/Istanbul\" vitest run",
+		"test:ui": "TZ=\"Europe/Istanbul\" vitest --ui",
+		"test:coverage": "TZ=\"Europe/Istanbul\" vitest run --coverage",
+		"lint": "run-p lint:*",
+		"lint:eslint": "eslint --cache --cache-location ./node_modules/.cache/eslint . --ext .js,.ts,.jsx,.tsx",
+		"lint:types": "tsc"
+	},
+	"dependencies": {
+		"semver": "^7.6.0",
+		"yargs": "^17.7.2"
+	}
+}

package/toCopy/playwright.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from "@playwright/test";
+import { playwrightConfig } from "@atomicsmash/test-utils";
+
+export default defineConfig(playwrightConfig, {
+	use: {
+		baseURL: `%%BASE_URL%%`,
+	},
+});

package/toCopy/tests/e2e/example.spec.ts

@@ -0,0 +1,18 @@
+import { test, expect } from '@playwright/test';
+
+test('has title', async ({ page }) => {
+  await page.goto('https://playwright.dev/');
+
+  // Expect a title "to contain" a substring.
+  await expect(page).toHaveTitle(/Playwright/);
+});
+
+test('get started link', async ({ page }) => {
+  await page.goto('https://playwright.dev/');
+
+  // Click the get started link.
+  await page.getByRole('link', { name: 'Get started' }).click();
+
+  // Expects page to have a heading with the name of Installation.
+  await expect(page.getByRole('heading', { name: 'Installation' })).toBeVisible();
+});

package/toCopy/tests/e2e/universal.spec.ts

@@ -0,0 +1,23 @@
+import {
+	doLighthouseTest,
+	checkPrivilegedPages,
+	checkForLoremIpsum,
+} from "@atomicsmash/test-utils";
+import { test, lighthouseTest, pagesToTest } from "../playwright-utils";
+
+test(
+	"privileged pages of the site to ensure non-logged in users can't access them",
+	checkPrivilegedPages(pagesToTest),
+);
+test("No lingering lorem ipsum on the site", checkForLoremIpsum(pagesToTest));
+
+for (const pageToTest of pagesToTest) {
+	lighthouseTest(
+		`${pageToTest.name} @desktop @lighthouse`,
+		doLighthouseTest(pageToTest, "desktop", true),
+	);
+	lighthouseTest(
+		`${pageToTest.name} @mobile @lighthouse`,
+		doLighthouseTest(pageToTest, "mobile", true),
+	);
+}

package/toCopy/tests/fixtures/testData.ts

@@ -0,0 +1,18 @@
+/**
+ * This file adds static test data to be available in all your tests.
+ * Currently, it only contains an array of valid phone numbers, but
+ * this could include any data you want.
+ */
+const phoneNumbers = [
+  '01234567890',
+  '+441234567890',
+  '00441234567890',
+  '0123 45 6789',
+  '0123456789',
+  '0123456789',
+  '(01234) 567 890',
+]
+
+export const testData = {
+  phoneNumbers,
+}

package/toCopy/tests/mocks/index.ts

@@ -0,0 +1,16 @@
+import type { RequestHandler } from 'msw'
+import closeWithGrace from 'close-with-grace'
+import { http } from 'msw'
+import { setupServer } from 'msw/node'
+
+const handlers: RequestHandler[] = []
+
+const server = setupServer(...handlers)
+
+server.listen({ onUnhandledRequest: 'warn' })
+// eslint-disable-next-line no-console
+console.info('🔶 Mock server installed')
+
+closeWithGrace({ delay: 1000 }, () => {
+  server.close()
+})

package/toCopy/tests/playwright-utils.ts

@@ -0,0 +1,42 @@
+import type {
+  AuthenticatePageFunction,
+  PageList,
+} from '@atomicsmash/test-utils'
+import type { Page } from '@playwright/test'
+import { getLighthouseTest } from '@atomicsmash/test-utils'
+import { test as base } from '@playwright/test'
+import { testData } from './fixtures/testData.js'
+
+/**
+ * Fixtures
+ */
+const logInUser: AuthenticatePageFunction = async function ({ page }, use) {
+  // Do any actions here to log a user in so you can access logged in areas of the site.
+  // This is useful for testing my account pages, etc.
+  await use(page)
+}
+
+type CustomFixtures = {
+  testData: typeof testData
+  authenticatedPage: Page
+}
+
+export const test = base.extend<CustomFixtures>({
+  testData: async (
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    { page },
+    use
+  ) => {
+    // Use the fixture value in the test.
+    await use(testData)
+  },
+  authenticatedPage: [logInUser, { scope: 'test' }],
+})
+
+export const lighthouseTest = getLighthouseTest(logInUser)
+export const { expect } = test // re-export expect to cleanup imports in tests
+export { checkAccessibility } from '@atomicsmash/test-utils'
+
+export const pagesToTest: PageList = [
+  // hover over PageList to see the format required for each page
+]