[WIP] Enable web extension for Foam

[pderaaij]

I am making a fresh attempt on getting Foam to work on the browser. I'll close #1127 later on, but am keeping it for reference. So far, so good. But long way to go.

[pderaaij]

Update:

The extension is running quite well in the online environment at first sight. To be sure - and for regression, I'd like to run the integration tests for web as well. This is where the pain begins.

Last time I got stuck in a long loop to get Mocha working, so this time I went for vitest. However, this is not an easy ride as well. Vitest works well for unit tests, but integration tests are the problem. For reference, we need to run the test suite programmatically. We need to start the vscode environment and then run the test suite (see: run-tests/ts). Support for programmatically is limited in vitest (https://vitest.dev/advanced/api.html). However, this only works in ESM mode. Vscode, due to electron, runs only commonjs (https://github.com/microsoft/vscode/issues/130367).

There seems to be some ways to get commonjs working in vscode, but I am wondering if we want all these changes just to get testing for web working.

For now, I feel vitest is not the way forward. However, I did learn a thing or two. I am going to have a fresh look at getting mocha working. But, fresh ideas are welcome.

[pderaaij]

I've been working on getting the tests to work with Mocha. Although it seemed I was making progress I ran into a big problem. Our assertion library is jest's expect. A library that's not easily replaced by chai or a other browser compatible assertion library. So, my conclusion is that if we really want to have tests for both extension and browser we would need to overhaul the current testing library, or maintain two libraries. Both are not preferable.

My suggestion is to enable the brwoser extension and only add a test suite that checks if Foam can be activated in the web browser. A pattern that I have seen at more VSCode extensions. This way we at least confirm the webpack bundle is okay and works. Specific checks for working functionality in the browser would not exist. Only perhaps if it is a recurring event in which we would write a specific regression test.

@riccardoferretti what do you think?

[riccardoferretti]

Thanks @pderaaij for the investigation.

My suggestion is to enable the brwoser extension and only add a test suite that checks if Foam can be activated in the web browser. A pattern that I have seen at more VSCode extensions [...] Specific checks for working functionality in the browser would not exist. Only perhaps if it is a recurring event in which we would write a specific regression test.

Mmmm.. can you share a couple of VS Code extensions that use that approach? I fear it might be a little brittle, but maybe I am missing something? I guess testing the activation would validate that imports and packages are valid, but wouldn't cover the actual runtime.. then when an issue arises we could cover it with an explicit test (which requires a new assertion library, see comment below). I am trying to figure out how big the window for uncaught bugs is with this approach..

Our assertion library is jest's expect. A library that's not easily replaced by chai or a other browser compatible assertion library. So, my conclusion is that if we really want to have tests for both extension and browser we would need to overhaul the current testing library, or maintain two libraries. Both are not preferable.

I am not against migrating over time to another library that would be more web friendly. Basically all new and edited tests would use the new library until we reach a point of switch over. I found some articles online of people that have done such thing, so at least we know it's possible.

[pderaaij]

Annoyingly enough I can't find these examples anymore in my history and a quick GitHub search leaves me blank as well. I have researched so many repo's I might lost track how often I have seen this pattern. I do agree it feels quite brittle.

We could first rewire the testing framework. Or we just publish the web extension and rewrite the tests based on incoming reports. But that's not the greatest experience. In any case, it will require some work.

[riccardoferretti]

Ok, this is something to think about, I am still debating if it's "good enough" (it might be). Can you get the PR in a place where all tests pass using jest? That feels like the first thing to ensure regardless.

I am open to your suggestion about using the legacy framework (jest) for the regular testing, and only have some smoke tests for the web extension.

[flancian]

Ahoy there! I come with few skills but willing to contribute help to try to merge this if I can provide any. I also know several other people who are interested in getting Foam to work on VS Code web :)

What's left to be done? Could the extension be merged as-is without interfering with code quality/stability for regular (non-browser-based) VS Code users, maybe with a warning/alpha disclaimer?

[pderaaij]

@riccardoferretti this would be enough to make the web version work. However, note-embedding will not work correctly. I might be able to get it working via: https://github.com/microsoft/vscode/issues/174080#issuecomment-1885857624.

Additionally, I have not been able to get a simple end-2-end test working. My idea was to simply test if the extension was loaded. But I can't get mocha to play along.

Nevertheless, we can publish the extension for web with these comments and start to collect the feedback.

[pderaaij]

It took some time, but I got an end-2-end test working. It is a simple check that asserts if the foam extension is loaded.

@riccardoferretti I've added an extra CI step to build and verify the web version is working. If you see this differently, let me know.

My goal would be to get this PR merged. The next step is to attempt to change the markdown preview.

[riccardoferretti]

Hi @pderaaij I was trying to test this locally, but I am getting the following error in the browser

Sequence of steps:

• checkout the branch
• yarn reset
• cd packages/foam-vscode
• yarn compile-web
• yarn package-web
• yarn open-in-browser
• Open foam-template
• go to getting-started.md (so far it is working as the links showing up in the "All Links" panel are correct)
• hover with the mouse on a link (interesting that the navigation still work)

Also, the Foam: Show Graph command doesn't work (seems related to the lookup of the webview).

Can you confirm the issues?

[pderaaij]

Yes, the Buffer one I found out as well. It is locally in my stage, but yet to commit. Will do so.

It is a webpack config issue by the way. Easily resolved.

[pderaaij]

Got the tests working:

Functionality should be working now. Let me know what you think @riccardoferretti

[riccardoferretti]

First of all, amazing work @pderaaij! This is not a simple change!

There is one thing that I am really hesitating on, and that's mocha. I normally wouldn't like to have 2 "competing" libraries, in this specific case the fact that it's for testing and the extra magic on the TS front makes me even more wary.

So, I am looking at the code and am trying to understand where jest falls short. Why can't packages/foam-vscode/src/test/web/index.ts use jest? I understand the limitations on the assertion library, and in that regard I would suggest we don't need an assertion library for two tests - if we can run them via jest. Can you help me understand?

Thanks!

[pderaaij]

As far as I understand the problem is that Jest is an unit testing library. It is designed to run within the nodejs environment, but not the browser.

The test suite runs in the browser. The vscode-web-test extension starts a local VS code web environment in which Foam is loaded. After activation the test suite runs in the browser. For this we need a browser library. `` mocha`. Is the suggested library by the vscode docs.

I know it isn't ideal, but it is the pattern I saw in many repositories.

[riccardoferretti]

I see what you mean. I was testing the extension and I am getting an error when showing the node graph, are you having the same issue?

[pderaaij]

@riccardoferretti Quite sure it was working, but can't understand how it could be working. I worked on a concept to make the graph working again. Could you verify if this works for your? run npm run compile-web before running npm run open-in-web