obsidian-testing-framework 0.0.4

package/README.md

@@ -0,0 +1,32 @@
+# the Obsidian Testing Framework 
+
+## what is this?
+
+this is a library that (finally!) lets you end-to-end test your obsidian plugins.
+it uses [playwright](https://playwright.dev/docs/intro) to interact with obsidian,
+which is an Electron app under the hood.
+
+## great! how do i use it?
+
+### basic usage
+```ts
+import {test} from "obsidian-testing-library";
+test('obsidian app url', async ({ page }) => {
+	console.log(page.url());
+	expect(/obsidian\.md/i.test(page.url())).toBeTruthy()
+});
+```
+### usage with the `app` instance
+```ts
+test("idk", async({page}) => {
+	console.log("idk")
+	let tfile = await doWithApp(page, async (app) => {
+		return app.metadataCache.getFirstLinkpathDest("Welcome", "/");
+	});
+	expect(tfile.basename).toEqual("Welcome")
+})
+```
+
+### other utilities
+
+see `src/util.ts` for the currently included utilities and their documentation.

package/lib/fixtures.d.ts

@@ -0,0 +1,9 @@
+import { ElectronApplication, JSHandle, Page } from "playwright";
+import { ObsidianTestingConfig } from "./index.js";
+import { App } from "obsidian";
+export interface ObsidianTestFixtures {
+    electronApp: ElectronApplication;
+    page: Page;
+    obsidian: ObsidianTestingConfig;
+    appHandle: JSHandle<App>;
+}

package/lib/fixtures.js

@@ -0,0 +1 @@
+export {};

package/lib/index.d.ts

@@ -0,0 +1,6 @@
+import { ObsidianTestFixtures } from "./fixtures.js";
+export interface ObsidianTestingConfig {
+    vault?: string;
+}
+export declare function getExe(): string;
+export declare const test: import("playwright/test").TestType<import("playwright/test").PlaywrightTestArgs & import("playwright/test").PlaywrightTestOptions & ObsidianTestFixtures, import("playwright/test").PlaywrightWorkerArgs & import("playwright/test").PlaywrightWorkerOptions>;

package/lib/index.js

@@ -0,0 +1,120 @@
+import { test as base } from "@playwright/test";
+import { _electron as electron } from "playwright";
+import path from "path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { pageUtils, waitForIndexingComplete } from "./util.js";
+import { randomBytes } from "crypto";
+export function getExe() {
+    checkToy();
+    if (process.platform == "win32") {
+        return path.join(process.env.LOCALAPPDATA, "Obsidian", "Resources", "app.asar");
+    }
+    const possibleDirs = [
+        "/opt/Obsidian",
+        "/usr/lib/Obsidian",
+        "/opt/obsidian",
+        "/usr/lib/obsidian",
+        "/var/lib/flatpak/app/md.obsidian.Obsidian/current/active/files",
+        "/snap/obsidian/current",
+    ];
+    for (let i = 0; i < possibleDirs.length; i++) {
+        if (existsSync(possibleDirs[i])) {
+            // console.log(execSync(`ls -l ${possibleDirs[i]}`).toString());
+            return path.join(possibleDirs[i], "resources", "app.asar");
+        }
+    }
+    return "";
+}
+function checkToy() {
+    if (process.platform == "darwin") {
+        throw new Error("use a non-toy operating system, dumbass");
+    }
+}
+function generateVaultConfig(vault) {
+    const vaultHash = randomBytes(8).toString("hex").toLocaleLowerCase();
+    let configLocation;
+    console.log("vault is", vault, existsSync(vault));
+    checkToy();
+    if (process.platform == "win32") {
+        configLocation = path.join(`${process.env.APPDATA}`, "Obsidian");
+    }
+    else {
+        configLocation = path.join(`${process.env.XDG_CONFIG_HOME}`, "obsidian");
+        try {
+            mkdirSync(configLocation, { recursive: true });
+        }
+        catch (e) { }
+    }
+    const obsidianConfigFile = path.join(configLocation, "obsidian.json");
+    if (!existsSync(obsidianConfigFile)) {
+        writeFileSync(obsidianConfigFile, JSON.stringify({ vaults: {} }));
+    }
+    const json = JSON.parse(readFileSync(obsidianConfigFile).toString());
+    if (!Object.values(json.vaults).some((a) => a.path === vault)) {
+        json.vaults[vaultHash] = {
+            path: vault,
+            ts: Date.now(),
+        };
+        writeFileSync(obsidianConfigFile, JSON.stringify(json));
+        writeFileSync(path.join(configLocation, `${vaultHash}.json`), "{}");
+        return vaultHash;
+    }
+    else {
+        return Object.entries(json.vaults).find(a => a[1].path === vault)[0];
+    }
+}
+const obsidianTestFixtures = {
+    electronApp: [
+        async ({ obsidian: { vault } }, run) => {
+            process.env.ELECTRON_DISABLE_SECURITY_WARNINGS = "true";
+            console.log("asar located at:", getExe());
+            let uriArg = "";
+            if (vault) {
+                let id = generateVaultConfig(vault);
+                if (!!id) {
+                    uriArg = `obsidian://open?vault=${encodeURIComponent(id)}`;
+                }
+            }
+            const electronApp = await electron.launch({
+                timeout: 60000,
+                args: [getExe(), uriArg].filter((a) => !!a),
+            });
+            electronApp.on("console", async (msg) => {
+                console.log(...(await Promise.all(msg.args().map((a) => a.jsonValue()))));
+            });
+            await electronApp.waitForEvent("window");
+            await run(electronApp);
+            await electronApp.close();
+        },
+        { timeout: 60000 },
+    ],
+    page: [
+        async ({ electronApp }, run) => {
+            const windows = electronApp.windows();
+            // console.log("windows", windows);
+            let page = windows[windows.length - 1];
+            await page.waitForLoadState("domcontentloaded");
+            try {
+                await waitForIndexingComplete(page);
+            }
+            catch (e) {
+                console.warn("timed out waiting for metadata cache. continuing...");
+            }
+            for (let fn of Object.entries(pageUtils)) {
+                await page.exposeFunction(fn[0], fn[1]);
+            }
+            page.on("pageerror", exc => {
+                console.error("EXCEPTION");
+                console.error(exc);
+            });
+            page.on("console", async (msg) => {
+                console.log(...(await Promise.all(msg.args().map((a) => a.jsonValue()))));
+            });
+            await run(page);
+        },
+        { timeout: 60000 },
+    ],
+    obsidian: [{}, { option: true }],
+};
+// @ts-ignore some error about a string type now having `undefined` as part of it's union
+export const test = base.extend(obsidianTestFixtures);

package/lib/util.d.ts

@@ -0,0 +1,82 @@
+import { App, TFile } from "obsidian";
+import { Page } from "playwright";
+/**
+ * asserts that the contents of the file at `path` is equal to `expectedContent`.
+ *
+ * @export
+ * @param {Page} page - a Playwright page
+ * @param {string} path - the file to check
+ * @param {string} expectedContent - the expected content
+ * @param {boolean} [cached=true] - whether to use `app.vault.cachedRead`
+ */
+export declare function assertFileEquals(page: Page, path: string, expectedContent: string, cached?: boolean): Promise<void>;
+/**
+ * asserts that the line at `lineNumber` in the file at `path` is equal
+ * to `expectedContent`.
+ *
+ * @export
+ * @param {Page} page - a Playwright page
+ * @param {string} path - the file to check
+ * @param {number} lineNumber - the line in the file to check (0-based)
+ * @param {string} expectedContent - the expected content
+ * @param {boolean} [cached=true] - whether to use `app.vault.cachedRead`
+ */
+export declare function assertLineEquals(page: Page, path: string, lineNumber: number, expectedContent: string, cached?: boolean): Promise<void>;
+/**
+ * asserts that the lines in the specified range are equal to the expected
+ * content.
+ *
+ * @export
+ * @param {Page} page - a Playwright page
+ * @param {string} path - the file to check
+ * @param {number} start - the start of the desired line range (0-based)
+ * @param {number} end - the end of the desired line range (1-based)
+ * @param {string} expected - the expected content
+ * @param {boolean} [cached=true] - whether to use `app.vault.cachedRead`
+ */
+export declare function assertLinesEqual(page: Page, path: string, start: number, end: number, expected: string, cached?: boolean): Promise<void>;
+/**
+ * asserts all lines in the given range match a regex.
+ *
+ * @export
+ * @param {Page} page - a Playwright page
+ * @param {string} path - the file to check
+ * @param {number} start - the start of the desired line range (0-based)
+ * @param {number} end - the end of the desired line range (1-based)
+ * @param {RegExp} regex - the regex to test against
+ * @param {boolean} [cached=true] - whether to use `app.vault.cachedRead`
+ */
+export declare function assertLinesMatch(page: Page, path: string, start: number, end: number, regex: RegExp, cached?: boolean): Promise<void>;
+/**
+ * reads the file at `path` and returns its contents
+ *
+ * @export
+ * @param {Page} page - a Playwright page
+ * @param {string} path the file to read
+ * @param {boolean} [cached=true] - whether to use `app.vault.cachedRead`
+ * @return {Promise<string>} the file's contents
+ */
+export declare function readFile(page: Page, path: string, cached?: boolean): Promise<string>;
+/**
+ * do something with the global `App` instance,
+ * and return the result of that invocation
+ *
+ * @export
+ * @typeParam - T the return type of the callback
+ * @typeParam - A the additional argument(s) to pass
+ * @param {Page} page - a Playwright page
+ * @param {((a: App, args?: A) => T | Promise<T>)} callback - the function to execute
+ * @param {A} [args] - optional arguments to pass to the callback
+ * @return {Promise<T>} a promise containing `callback`'s return value (if any)
+ */
+export declare function doWithApp<T = unknown, A = any>(page: Page, callback: (a: App, args?: A) => T | Promise<T>, args?: A): Promise<T>;
+/**
+ * @internal
+ */
+export declare function waitForIndexingComplete(page: Page): Promise<unknown>;
+/**
+ * @internal
+ */
+export declare const pageUtils: {
+    getFile: (file: string) => TFile;
+};

package/lib/util.js

@@ -0,0 +1,135 @@
+import { expect } from "@playwright/test";
+/**
+ * asserts that the contents of the file at `path` is equal to `expectedContent`.
+ *
+ * @export
+ * @param {Page} page - a Playwright page
+ * @param {string} path - the file to check
+ * @param {string} expectedContent - the expected content
+ * @param {boolean} [cached=true] - whether to use `app.vault.cachedRead`
+ */
+export async function assertFileEquals(page, path, expectedContent, cached = true) {
+    const fileContent = await readFile(page, path, cached);
+    expect(fileContent).toEqual(normalizeEOL(expectedContent));
+}
+/**
+ * asserts that the line at `lineNumber` in the file at `path` is equal
+ * to `expectedContent`.
+ *
+ * @export
+ * @param {Page} page - a Playwright page
+ * @param {string} path - the file to check
+ * @param {number} lineNumber - the line in the file to check (0-based)
+ * @param {string} expectedContent - the expected content
+ * @param {boolean} [cached=true] - whether to use `app.vault.cachedRead`
+ */
+export async function assertLineEquals(page, path, lineNumber, expectedContent, cached = true) {
+    const fileContent = await readFile(page, path, cached);
+    expect(fileContent.split("\n")[lineNumber]).toEqual(normalizeEOL(expectedContent));
+}
+/**
+ * asserts that the lines in the specified range are equal to the expected
+ * content.
+ *
+ * @export
+ * @param {Page} page - a Playwright page
+ * @param {string} path - the file to check
+ * @param {number} start - the start of the desired line range (0-based)
+ * @param {number} end - the end of the desired line range (1-based)
+ * @param {string} expected - the expected content
+ * @param {boolean} [cached=true] - whether to use `app.vault.cachedRead`
+ */
+export async function assertLinesEqual(page, path, start, end, expected, cached = true) {
+    const fileContent = await readFile(page, path, cached);
+    const lines = fileContent.split("\n").slice(start, end);
+    const expectedLines = normalizeEOL(expected).split("\n");
+    expect(lines.every((l, i) => l == expectedLines[i])).toEqual(true);
+}
+const getFile = (file) => {
+    let f = window.app.vault.getFileByPath(file);
+    if (!f) {
+        throw new Error("File does not exist in vault.");
+    }
+    return f;
+};
+/**
+ * asserts all lines in the given range match a regex.
+ *
+ * @export
+ * @param {Page} page - a Playwright page
+ * @param {string} path - the file to check
+ * @param {number} start - the start of the desired line range (0-based)
+ * @param {number} end - the end of the desired line range (1-based)
+ * @param {RegExp} regex - the regex to test against
+ * @param {boolean} [cached=true] - whether to use `app.vault.cachedRead`
+ */
+export async function assertLinesMatch(page, path, start, end, regex, cached = true) {
+    const fileContent = await readFile(page, path, cached);
+    const lines = fileContent.split("\n").slice(start, end);
+    expect(lines.every(l => regex.test(l))).toEqual(true);
+}
+/**
+ * reads the file at `path` and returns its contents
+ *
+ * @export
+ * @param {Page} page - a Playwright page
+ * @param {string} path the file to read
+ * @param {boolean} [cached=true] - whether to use `app.vault.cachedRead`
+ * @return {Promise<string>} the file's contents
+ */
+export async function readFile(page, path, cached = true) {
+    const fn = getFile.toString();
+    return normalizeEOL(await doWithApp(page, async (app, args) => {
+        const gf = eval(`(${args.getFile})`);
+        const file = gf(args.path);
+        return await (args.cached ? app.vault.cachedRead(file) : app.vault.read(file));
+    }, { path, cached, getFile: fn }));
+}
+/**
+ * do something with the global `App` instance,
+ * and return the result of that invocation
+ *
+ * @export
+ * @typeParam - T the return type of the callback
+ * @typeParam - A the additional argument(s) to pass
+ * @param {Page} page - a Playwright page
+ * @param {((a: App, args?: A) => T | Promise<T>)} callback - the function to execute
+ * @param {A} [args] - optional arguments to pass to the callback
+ * @return {Promise<T>} a promise containing `callback`'s return value (if any)
+ */
+export async function doWithApp(page, callback, args) {
+    const cbStr = callback.toString();
+    return await page.evaluate(async ({ __callback: cb, args }) => {
+        const func = new Function("args", `return ((${cb}))(window.app, args)`);
+        return await func(args);
+    }, { __callback: cbStr, args });
+}
+/**
+ * @internal
+ */
+export function waitForIndexingComplete(page) {
+    return page.evaluateHandle("window.app").then((appHandle) => {
+        return appHandle.evaluate((app) => {
+            return new Promise((res2, rej2) => {
+                let resolved = false;
+                app.metadataCache.on("resolved", () => {
+                    res2(null);
+                    resolved = true;
+                });
+                setTimeout(() => !resolved && rej2("timeout"), 10000);
+            });
+        });
+    });
+}
+/**
+ * @internal
+ */
+function normalizeEOL(str) {
+    return str.split(/\r\n|\r|\n/).join("\n");
+}
+/**
+ * @internal
+ */
+export const pageUtils = {
+    getFile,
+};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "obsidian-testing-framework",
+  "packageManager": "yarn@4.5.1",
+  "dependencies": {
+    "@codemirror/language": "https://github.com/lishid/cm-language",
+    "@codemirror/state": "^6.0.1",
+    "@codemirror/view": "^6.0.1",
+    "@playwright/test": "^1.48.1",
+    "asar": "^3.2.0",
+    "electron": "^33.0.2",
+    "obsidian": "latest",
+    "playwright": "^1.48.1",
+    "tmp": "^0.2.3",
+    "typescript": "^5.6.3",
+    "xvfb-maybe": "^0.2.1"
+  },
+  "files": [
+    "./lib",
+    "../../README.md"
+  ],
+  "readme": "",
+  "version": "0.0.4",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./utils": {
+      "types": "./lib/util.d.ts",
+      "default": "./lib/util.js"
+    },
+    "./fixture": {
+      "types": "./lib/fixtures.d.ts",
+      "default": "./lib/fixtures.js"
+    }
+  },
+  "main": "./lib/index.js",
+  "typings": "./lib/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "lint": "tslint -c tslint.json src/**/*.ts",
+    "prepublishOnly": "rm README.md && cp ../../README.md . && rimraf lib && npm run build"
+  },
+  "devDependencies": {
+    "@types/tmp": "^0",
+    "rimraf": "^6.0.1",
+    "vitest": "^2.1.3"
+  },
+  "type": "module"
+}