sefiutils 1.0.46 → 1.0.48

package/src/globalSetup.ts

@@ -0,0 +1,116 @@
+import dotenv from "dotenv";
+dotenv.config() // read ".env"
+
+import path from "path";
+import fs, { writeFileSync } from "fs";
+import { debug, verbose } from "./log";
+import { getRemoteAddressAndPort } from "./seUtils";
+import { homedir } from "os";
+
+declare global {
+    var server: any; // only loaded in remote case; this global variable is only visible in globalTeardown.ts
+        // and not in the tests, cf. https://jestjs.io/docs/configuration#globalsetup-string
+}
+/**
+ * This function is called by Jest once before all tests are executed. 
+ * In order to get called, it must be referenced in the jest configuration file:
+ * ```
+ * "globalSetup": "<rootDir>/tests/globalSetup.ts"
+ * ```
+ *  
+ * **Important Note**: "Any global variables that are defined through globalSetup can only be 
+ * read in globalTeardown. You cannot retrieve globals defined here in your test suites."
+ * [Jest Documentation](https://jestjs.io/docs/configuration#globalsetup-string)
+ * 
+ * We only start the selenium server here if we are running in remote mode, which is the default.
+ * The mode can configured by setting the environment variable BROWSER to "chrome", "firefox" or "remote".
+ * 
+ * Do not forget a global teardown function, which is called after all tests are executed,
+ * cf. globalTeardown.ts
+ */
+export default async function setGlobalObjects() {
+    const browser = (process.env.SEFI_BROWSER as "chrome" | "firefox" | "remote") || "remote";
+
+    verbose(`Global Setup: Use browser: ${browser}`);
+    try {
+        if (browser === "remote") {
+            await setUpSeleniumServer();
+        } 
+    } catch (err) {
+        console.error(`Error setting up server: ${err}`);
+        throw err;
+    }
+}
+
+/**
+ * Returns the path to the (cached) selenium server jar file. The jar file is automatically downloaded
+ * if it is not already cached.
+ * 
+ * The version of the selenium server can be configured by setting the environment variable 
+ * `SELENIUM_SERVER_VERSION`. If not set, the default version is 4.16.1.
+ * 
+ * The jar file is cached in the `.cache` directory in the project root.
+ * 
+ * @returns the path to the selenium server jar file
+ */
+export async function getSeleniumServerJar() {
+    const seleniumServerVersion = process.env.SEFI_SELENIUM_SERVER_VERSION || "4.16.1";
+    const versionParts = seleniumServerVersion.split(".").map(s => parseInt(s));
+    if (versionParts.length !== 3) {
+        throw new Error(`Invalid version number: ${seleniumServerVersion}`);
+    }
+    const jarName = `selenium-server-${versionParts[0]}.${versionParts[1]}.${versionParts[2]}.jar`;
+    const homeDir = homedir();
+    const cachedPath = path.resolve(path.join(homeDir, ".cache", "selenium-server", jarName));
+    verbose(`Selenium server jar: ${cachedPath}`);
+    if (! fs.existsSync(cachedPath)) {
+        if (! fs.existsSync(path.dirname(cachedPath))) {
+            fs.mkdirSync(path.dirname(cachedPath));
+        }   
+        const downloadURL = process.env.SEFI_SELENIUM_SERVER_DOWNLOAD_URL || "https://github.com/SeleniumHQ/selenium/releases/download";
+        const url = `${downloadURL}/selenium-${versionParts[0]}.${versionParts[1]}.0/${jarName}`;
+        console.log(`Download ${url} to ${cachedPath}`);
+        const response = await fetch(url);
+        if (response.status !== 200) {
+            throw new Error(`Error downloading ${url}: ${response.status} ${response.statusText}`);
+        }
+        const blob = await response.blob();
+        const buffer = Buffer.from(await blob.arrayBuffer());
+        writeFileSync(cachedPath, buffer);
+    } else {
+        verbose(`Selenium server jar already cached`);
+    }
+    return cachedPath;
+}
+
+
+async function setUpSeleniumServer() {
+    debug("Dynamic import of selenium-webdriver/remote")
+    const remote = await import("selenium-webdriver/remote");
+    
+    const jarPath = await getSeleniumServerJar();
+
+    if (globalThis.server) {
+        await globalThis.server.kill();
+        verbose("`Server killed before starting again");
+    }
+
+    const { port} = getRemoteAddressAndPort();
+
+    debug(()=>`Start selenium server at port ${port} with SE_NODE_MAX_SESSIONS=4, SE_NODE_OVERRIDE_MAX_SESSIONS=true`);
+    const s = new remote.SeleniumServer(jarPath, {
+        port: port,
+        env: {
+            ...process.env,
+            "SE_NODE_MAX_SESSIONS": "4",
+            "SE_NODE_OVERRIDE_MAX_SESSIONS": "true",
+            // "JAVA_OPTS": "-XX:ActiveProcessorCount=4"
+        }
+    });
+    
+    const timeout = parseInt(process.env.SEFI_SELENIUM_SERVER_START_TIMEOUT || "5000");
+    const actualAddress = await s.start(timeout);
+    globalThis.server = s;
+    // const address = await globalThis.server.address()
+    debug(()=>`Selenium server started at: ${actualAddress}`);
+}

package/src/globalTeardown.ts

@@ -0,0 +1,22 @@
+
+/**
+ * This function is called by Jest once after tests have been executed. 
+ * In order to get called, it must be referenced in the jest configuration file:
+ * ```
+ * "globalTeardown": "<rootDir>/tests/globalTeardown.ts"
+ * ```
+ * **Important Note**: "Any global variables that are defined through globalSetup can only be 
+ * read in globalTeardown. You cannot retrieve globals defined here in your test suites."
+ * [Jest Documentation](https://jestjs.io/docs/configuration#globalsetup-string)
+ * 
+ * Here, we stop the remote selenium server if it was started in globalSetup.ts.
+ */
+export default async function killServer() {
+    if (globalThis.server) {
+        await server.kill();
+        console.log(`global Teardown: Server killed`);
+    } else {
+        console.log(`global Teardown: No server to kill`);
+    }
+    globalThis.server = undefined;
+}

package/src/localSetup.ts

@@ -0,0 +1,128 @@
+import dotenv from "dotenv";
+dotenv.config() // read ".env"
+
+import { Builder, Capabilities, WebDriver } from "selenium-webdriver";
+import { getRemoteAddressAndPort, setBrowserWindowSize, setViewPortSize } from "./seUtils";
+import { debug, verbose } from "./log";
+
+export const LOCAL_SETUP_TIMEOUT = 20000;
+
+export async function localSetup(page: string, width = 500, height = 500, acceptUntrustedCertificates = true): Promise<WebDriver> {
+    debug(() => `localSetup("${page}", ${width}, ${height}, ${acceptUntrustedCertificates}), getWebDriver ...`);
+    const driver = await getWebDriver(acceptUntrustedCertificates);
+    verbose(() => `Driver started, load page: ${page}`);
+    await driver.get(page);
+    debug(() => `Page loaded, set browser window size: ${width}x${height}`);
+    await setBrowserWindowSize(driver, width, height);
+    debug("Page loaded and window size set, local setup done, return driver.")
+    return driver;
+}
+
+/**
+ * To be configured in jest setup file via globalSetup as it needs to be run before any tests in all files.
+ * Additionally, 
+ * ```
+ * await driver.get(page);
+ * await setViewPortSize(500, 500);
+ * ```
+ * are to be called.
+*/
+async function getWebDriver(acceptUntrustedCertificates: boolean) {
+    const browser = (process.env.SEFI_BROWSER as "chrome" | "firefox" | "remote") || "remote";
+
+    debug(() => `Use browser: ${browser}`);
+    try {
+        if (browser === "chrome") {
+            return await setUpWebDriverChrome(acceptUntrustedCertificates);
+        } else if (browser === "firefox") {
+            return await setUpWebDriverFirefox(acceptUntrustedCertificates);
+        } else if (browser === "remote") {
+            return await setUpWebDriverInDocker(acceptUntrustedCertificates);
+        } else {
+            throw new Error(`Unknown browser: ${browser}`);
+        }
+    } catch (err) {
+        console.error(`Error setting up driver: ${err}`);
+        throw err;
+    }
+}
+
+
+async function setUpWebDriverInDocker(acceptUntrustedCertificates: boolean) {
+    debug("Dynamic import of selenium-webdriver/firefox");
+    debug("Remote browser, load firefox webdriver");
+    const firefox = await import('selenium-webdriver/firefox');
+
+    const { address } = getRemoteAddressAndPort();
+    const start = Date.now();
+
+    const options = new firefox.Options().addArguments("-headless");
+    options.setAcceptInsecureCerts(acceptUntrustedCertificates);
+
+    debug(() => `Start headless firefox, remote server at ${address}`)
+    const driver = await new Builder()
+        .usingServer(address)
+        .withCapabilities(Capabilities.firefox())
+        .setFirefoxOptions(options)
+        .build();
+
+    debug(() => {
+        const duration = (Date.now() - start) / 1000;
+        return `Driver resolved and connected, required ${duration}s.`
+    });
+    return driver;
+}
+
+
+/**
+ * To be called in the beforeAll() function of a test suite.
+ * Additionally, 
+ * ```
+ * await driver.get(page);
+ * await setViewPortSize(500, 500);
+ * ```
+ * are to be called.
+ */
+async function setUpWebDriverChrome(acceptUntrustedCertificates: boolean) {
+    debug("Dynamic import of chromedriver and selenium-webdriver/chrome");
+    //@ts-ignore
+    await import('chromedriver');
+    const chrome = await import('selenium-webdriver/chrome');
+
+    const options = new chrome.Options().addArguments("--headless=new");
+    options.setAcceptInsecureCerts(acceptUntrustedCertificates);
+
+    debug(() => `Start headless chrome`)
+    const driver = await new Builder()
+        .forBrowser('chrome')
+        .setChromeOptions(options)
+        .build();
+    return driver;
+}
+
+/**
+ * To be called in the beforeAll() function of a test suite.
+ * Additionally, 
+ * ```
+ * await driver.get(page);
+ * await setViewPortSize(500, 500);
+ * ```
+ * are to be called.
+ */
+async function setUpWebDriverFirefox(acceptUntrustedCertificates: boolean) {
+    debug("Dynamic import of geckodriver and selenium-webdriver/firefox");
+    //@ts-ignore
+    await import('geckodriver'); // installed geckodriver will cause remote configuration to fail in docker...
+    const firefox = await import('selenium-webdriver/firefox');
+
+    const options = new firefox.Options().addArguments("-headless");
+    options.setAcceptInsecureCerts(acceptUntrustedCertificates);
+
+    debug(() => `Start headless firefox`)
+    const driver = await new Builder()
+        .forBrowser('firefox')
+        .setFirefoxOptions(options)
+        .build();
+
+    return driver;
+}

package/src/localTeardown.ts

@@ -0,0 +1,14 @@
+import { WebDriver } from "selenium-webdriver";
+
+/**
+ * To be called in the afterAll() function of a test suite.
+ */
+export async function localTeardown(driver: WebDriver) {
+    if (driver) {
+        await driver.quit();
+        // console.log(`Driver quit`);
+    } else {
+        throw new Error("Driver not started yet");
+
+    }
+}

package/src/log.ts

@@ -0,0 +1,19 @@
+const logLevel = (process.env.SEFI_LOG_LEVEL || "info").toLowerCase();
+
+export function verbose(msg: any) {
+    if (logLevel=="debug" || logLevel=="verbose") {
+        if (msg instanceof Function) {
+            msg = msg();
+        }
+        console.log(msg);
+    }
+}
+
+export function debug(msg: any) {
+    if (logLevel=="debug") {
+        if (msg instanceof Function) {
+            msg = msg();
+        }
+        console.log(msg);
+    }
+}