Some improvement ideas about code infra

[teobler]

Hello, AFFiNE team.

Glad to see such a significant advancement since AFFiNE's initial open source release! Congratulations!

While looking over numerous AFFiNE repos, I discovered some infra areas that might be improved and would like to discuss them first.

Monorepo

We can see that AFFiNE and blocksuit both use monorepos to handle a number of packages via pnpm workspace.

To achieve a high-performance experience of running tests and building, etc., we can import another build system like NX, Turborepo(my prefer, can explain more about this), and lerna(deprecated).

For each package task within the workspace, these technologies offer features like caching and dependency graphs. These kinds of features ensure that each task only runs when necessary to save time.

I believe that this will improve local and CI experience, particularly with larger and larger projects.

Structure Testing

E2E tests and unit tests are currently combined in one subdirectory (__tests__).

The project's e2e tests and unit tests are now combined in a single folder and are differentiated by lengthy suffixes. The fact that e2e tests use playwright and unit tests use vitest, which do not use the same technological stack, may cause some issues:

• Unit tests provide the quickest feedback, are subject to change at any time, and are placed in the same level of test folder as the test file to allow for quick changes and quick runs with the IDE (entire directory of test files), whereas e2e is mixed with unit tests and loses this consistency.

  

• This combinition leads to unnecessarily long suffixes in the unit test files, which can be made worse when the file name under test is also long.

• I would recommend putting all e2e tests in the same directory(like tests or e2e in root dir) if there is no particular understanding (some of the tests for the store package are now in a separate package).

  • for reasons similar to the previous one. e2e tests typically require launching the entire app and running a series of real user journeys; placing them in a separate folder makes it easier to schedule all user journeys. The test cases can be organized in a separate folder to distinguish between the various test cases even when the test case is for the store package but the problems may come from other packages of the app.

Please excuse me if I am mistaken; of course, the aforementioned observations are merely my subjective assessment and I may not be aware of the context in which such things were done.

I also recognize that the team is concentrating on some fantastic new features, and if I can offer any PR for enhancements, I'd be delighted to do so!

[doodlewind]

Hi @teobler, thanks for your feedback and your interest in BlockSuite!

As the author of BlockSuite, I think it could be helpful to share the underlying design of monorepo and testing separately.

Monorepo

Regarding monorepo, IMO we are already reaching a state that may not require Nx, Turborepo, or Lerna to speed things up. Since we are using Vite for bundle-less testing (in both Vitest and Playwright), which means we even don't build before running tests, so there is barely the need for caching build artifacts and the deps graph (but I guess the Vite build-cache is also being utilized in packages/playground/node_modules/.vite). As for building, we are already an ESM-only monorepo, so the build process in the packages is only doing tsc transpiling, and it's also fast enough for us.

Currently with these setups, running test.only for a single E2E test case can be finished almost instantly, and the local testing for nearly 150 test cases only costs about 30 seconds in an M1 pro device.

TDD

Regarding TDD, maybe it's better to think about "editor-level testing" and "package-level testing". We are adding Playwright test cases at the editor level since rich-editing features are easy to have regression. They represent the "editor user journey" (.e.g., indenting a list or pasting a paragraph) indeed, and that's what lexical is doing.

But at the package level, things could be different. I believe the principle is that when one package is updated, only its package-level test cases (and the editor-level tests) should run. But the specific package-level testing methods can be very different.

For example, we are adding pnpm test:store that tests only the store package (its CI configuration could be optimized). Note that this command is not only using UT or E2E tools standalone but a mix of them:

# output of `pnpm test:store`
# It's running in Playwright,
# but the "✅" here is generated inside the browser, rather than Node
...

Running 3 tests using 1 worker

  ✓  1 blob/__tests__/blob.spec.ts:7:1 › blob storage basics (337ms)
✅ can init provider
✅ can store image
✅ can trigger event
✅ can delete image
✅ can clear storage
  ✓  2 blob/__tests__/blob.spec.ts:13:1 › blob state after refresh (307ms)
✅ can set blob
✅ can get saved blob
  ✓  3 workspace/__tests__/workspace.spec.ts:7:1 › workspace basics (206ms)
✅ can create page

This happens because, in this package, we need to test features related to IndexedDB, so this is more like a browser-side UT that run asserts inside the browser. Some other examples:

• For future testing of the phasor package (our canvas framework), we may also need to test graphics features inside the browser. I'm not sure if using Vitest or Jest directly could be the best fit here. To make this happen, we are having different pages in playground/examples, making them the test entry points. And this could be a kind of "examples as tests" pattern.
• For future testing of our rich editor package, using playwright can be very handy.

So we are focused on test efficiency and will continue to try to create test solutions that are as efficient as possible, based on the mindset that reflects the difference between editor-level and package-level.

Thanks again for your advice, hope this can answer your confusion!