Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add unit tests for "staying on the same page when switching versions" functionality #7338

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open

Add unit tests for "staying on the same page when switching versions" functionality #7338

wants to merge 4 commits into from

Commits on Sep 19, 2024

  1. Extract function for core logic of "staying on the same page when swi… 

    …tching versions"

We will add unit tests for this functions in the next commit.

The function gets its own file because I was unable to get the test runner ("mocha") to work otherwise. See the child commit's description for more details.
    @ilyagr
    ilyagr committed Sep 19, 2024
    Configuration menu
    Copy the full SHA
    37ce702 View commit details
    Browse the repository at this point in the history

  2. Add unit tests for "staying on the same page when switching versions"… 

    … functionality

This is meant to simplify checking correctness of code like squidfunk#7227 and fixing bugs like squidfunk#7226. In fact, I'm hoping to eventually make this code general enough that it runs locally with `mike serve`.

I picked `mocha` as the testing library because its Typescript support
relies on ts-node, which this project already relies on. I have little experience with `mocha` vs `jest` vs something else beyond this commit.

See also https://github.com/mochajs/mocha-examples/tree/main/packages/typescript

Instead of using `chai`, I'm using Node's assert package.
Its TS types are in `@types/node`. It should be trivial, and might be good, to switch to `chai` or something else.

This setup is not perfect, in particular I can't get tests to import the whole `index.ts` file. This is why the function being tested gets its own file. Importing `index.ts` would seem to require writing some DOM shims and be a general headache.

For the record, using `tsx` and `jsdom-global` instead of `ts-node` to run `mocha` seemed like the most promising approach, but it still failed since some files imported from this `index.ts` rely on the DOM having some particular structure in their top-level definitions.

Here's how to set up `tsx` and `jsdom-global`, for reference:

```diff
diff --git a/.mocharc.json b/.mocharc.json
index e713305556...33c9adc84d 100644
--- a/.mocharc.json
+++ b/.mocharc.json
@@ -2,5 +2,5 @@
     "$schema": "https://json.schemastore.org/mocharc.json",
     "extension": ["ts"],
     "spec": "src/**/**.test.ts",
-    "require": "ts-node/register"
+    "require": ["tsx", "jsdom-global/register"]
 }
diff --git a/package.json b/package.json
index ecc9f98cf9...10242ca725 100644
--- a/package.json
+++ b/package.json
@@ -76,6 +76,7 @@
     "gitlab": "^14.2.2",
     "google-fonts-complete": "jonathantneal/google-fonts-complete",
     "html-minifier": "^4.0.0",
+    "jsdom-global": "^3.0.2",
     "material-design-color": "^2.3.2",
     "material-shadows": "^3.0.1",
     "mocha": "^10.6.0",
@@ -99,6 +100,7 @@
     "svgo": "3.0.0",
     "tiny-glob": "^0.2.9",
     "ts-node": "^10.9.2",
+    "tsx": "^4.16.2",
     "typescript": "^5.5.2"
   },
   "engines": {
```

I can also incorporate the diff into this commit.
    @ilyagr
    ilyagr committed Sep 19, 2024
    Configuration menu
    Copy the full SHA
    de986f9 View commit details
    Browse the repository at this point in the history

  3. tests: Demo limitations of "staying on the same page" functionality

    @ilyagr
    ilyagr committed Sep 19, 2024
    Configuration menu
    Copy the full SHA
    f98cb87 View commit details
    Browse the repository at this point in the history

  4. Tests: move to separate dir, use Jasmine instead of Mocha 

    I tried to follow the suggestions from squidfunk#7350 (comment) as best I can.

The suggested `iframe-worker` template uses Karma, but I didn't use it because 1) it's a complicated tool I don't understand and 2) it says it's deprecated and isn't even accepting bugfixes in https://github.com/karma-runner/karma Instead, I followed https://www.innoq.com/en/blog/2020/04/ts-jasmine-karma/#executingtestsonnode.js to set up Jasmine with ts-node, since that's all I need for this application. If you need something like Karma or whatever replaced it, you can always rework this later.

OTOH, let me know if there's more I can do to make this easier for you to review/maintain. I'm trying to make the minimal changes to the project structure possible, so that it's easy to change anything about this setup later.
    @ilyagr
    ilyagr committed Sep 19, 2024
    Configuration menu
    Copy the full SHA
    b46e0c2 View commit details
    Browse the repository at this point in the history