Fixes to "staying on the same page functionality" #7350
Conversation
ilyagr
force-pushed
the
fixbug
branch
3 times, most recently
from
3980fa8
to
04bc421
Compare
|
Thanks for the PR. However, the next time, before taking on work, please first discuss this with us as part of an issue or discussion, because we can omit unnecessary work first talking about it. We have no interest in using mocha as a test runner, as all my other projects use Jasmine, as it comes with everything included. Additionally, I always store my tests in a separate folder (see iframe-worker). Please split the entire testing logic into a separate PR, so we can discuss how we want to set up the environment, because there currently is none. We cannot merge this PR as it contains changes to the project structure, as well as changes to the business logic. I hope for your understanding – after all, it's me that has to maintain it. |
There seems to be some miscommunication, this is exactly what #7338 is. If/when we merge that one, this PR will become much smaller and will only include changes to business logic. I tried to explain my my plans and motivation as best I could there, as well. I'm not sure I was fully successful in explaining the relevance of that PR. In any case, I'm happy to adjust (Update: an now am done adjusting) that PR to something that works for you, as best as I can. Thanks for the pointer to I certainly appreciate the time you put into maintaining this project. My hope is to ultimately minimize your maintenance burden for this particular feature, which is currently very awkward to test changes to as you said yourself. |
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.
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.
…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.
… 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.
The new implementation should be very flexible. Fixes squidfunk#7226 Additionally, this allows using the version switcher even if the website is published at a different URL than the `site_url`. In particular, the version switcher should now work locally when serving the site with `mike serve`. The tests should demonstrate correctness of the implementation.
I polyfilled `URL.parse` since many browsers don't support it yet, apparently. I'd like this function to never throw an exception, any error should lead to it simply returning `undefined`.
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.
|
The new implementation should be very flexible.
Fixes #7226
Additionally, this allows using the version switcher even if the website is published at a different URL than the
site_url. In particular, the version switcher should now work locally when serving the site withmike serve.The tests should demonstrate correctness of the implementation.
This PR builds upon and includes #7338. The idea is that if you can be convinced
that #7338 is safe (it should be a clear no-op), the tests should be enough to convince you of the correctness
of the additional commits in this PR (they only change the
selectedVersionCorrespondingURLfunction), despite the significant change to the logic.I looked at #7227 and left a comment about how we could use that approach as well, but I think the approach here is much more flexible.
It's possible that there are more situations that we should test; let me know if you can think of some. For each significant case I'm aware of, I made a test based on exploring what happens in that case in a debugger.
I find it difficult to imagine a case when the old code will work and the new code won't, but it's possible to also keep the old logic in the function and guarantee that it will succeed whenever it succeeded before.
See commit descriptions for more details.