feat(custom-esbuild): add unit-test builder

[th0r]

PR Checklist

Please check if your PR fulfills the following requirements:

• Tests for the changes have been added (for bug fixes / features)
• Docs have been added / updated (for bug fixes / features)

PR Type

What kind of change does this PR introduce?

[ ] Bugfix
[x] Feature
[ ] Code style update (formatting, local variables)
[ ] Refactoring (no functional changes, no api changes)
[ ] Build related changes
[ ] CI related changes
[x] Documentation content changes
[ ] Other... Please describe:

Issue Number: #1932

What is the new behavior?

This PR adds an @angular-builders/custom-esbuild:unit-test builder which is based on the @angular/build:unit-test experimental builder, but allows to specify a list of custom ESBuild plugins via plugins option.

Does this PR introduce a breaking change?

[ ] Yes
[x] No

[just-jeb]

Thank you for your contribution!

In general LGTM, a few things:

1. I don't see a reason to update the minimal required version of angular packages for other builders. Could you elaborate on that?
2. We miss an actual e2e test that checks that it actually works with a real Angular app. Look how it's done for custom-webpack:karma - there is a unit test in examples/custom-webpack/full-cycle-app (app.component.spec.ts) that tests that functionality of the custom webpack config was applied during the test. The test is called "should render version in div with version css class". It is then tested as part of CI using packages/custom-webpack/scripts/ci.sh by running yarn test (which, in turn, triggers ng test target). We need a similar thing for the new builder you added.
3. The build fails in CI (I think b/c of custom-webpack), I presume it's because of some versions mismatch but not sure. I recommend to run the CI scripts locally to make sure the other builders tests and builds pass properly.

[th0r]

Thanks a lot of the review!

1. I had to update the minimal version because they've exported UnitTestBuilderOptions only in @angular/[email protected] which lead to updates in other related packages.
2. and 3. Will take a look tomorrow

[th0r]

Couldn't get the reason for these resolutions - looks like everything works fine without them.

[just-jeb]

Mostly historical, if it works now without then all good.

[th0r]

@just-jeb added tests and fixed the build. Could you take a look once more please?

[th0r]

Had to use ^ versions of angular packages here as otherwise yarn installs different versions of those packages for examples and packages which results in a broken build.

[just-jeb]

Should probably just bump the version here to match the minimal required package versions (which I though you updated). In general the examples are designed to serve as a real app with strict dependencies, partially in order to validate this issue - version matching.

[th0r]

I've updated the minimal versions of the packages only in custom-esbuild package as this is the only one that requires a version bump. There is no need to bump versions in other packages as they're unrelated.

But the real reason I added ^ in all examples is because without it yarn installs different versions of angular modules for @angular-builders/custom-esbuild package and for examples/custom-esbuild/* examples.

For instance, it installs @angular/[email protected] for the @angular-builders/custom-esbuild and @angular/[email protected] for the examples/custom-esbuild/sanity-esbuild-app:

The similar issue happens for custom-webpack examples - yarn installs different versions of @angular-devkit/build-angular for the @angular-builders/custom-webpack package and for e.g. examples/custom-webpack/sanity-app which leads to a different versions of webpack being installed:

This webpack versions mismatch causes the following error during yarn ci:

TypeError: The 'compilation' argument must be an instance of Compilation

So the only solution I found to make yarn install a single version of each angular package (dedupe them) is to loosen package versions in examples.

@just-jeb maybe you have some other thoughts?

[th0r]

Can't add vitest to example's package.json as in this case angular unit-test builder can't find it and ng test fails with the corresponding error.

[just-jeb]

vitest should be a peer dependency in the custom-esbuild package, and a dev dependency in the example app. But having it here is kinda workaroundish.

[nikita-ezhkov]

@just-jeb could you take a look one more time?
We really need this PR for a huge project

[just-jeb]

Sorry guys, I was off the radar for quite a while, looking now 👀.

[just-jeb]

@th0r Very nice job, love it!
Left a few minor comments, mostly about versioning and deps, mind taking a look?
I'd say it's already mergeable but if we addressed those first would be awesome.

[just-jeb]

Should probably just bump the version here to match the minimal required package versions (which I though you updated). In general the examples are designed to serve as a real app with strict dependencies, partially in order to validate this issue - version matching.

[just-jeb]

Same here regarding the versions

[just-jeb]

Same here regarding the versions

[just-jeb]

Same here regarding the versions

[just-jeb]

Same here regarding the versions

[just-jeb]

Same here regarding the versions

[just-jeb]

Same here regarding the versions

[just-jeb]

Mostly historical, if it works now without then all good.

[just-jeb]

vitest should be a peer dependency in the custom-esbuild package, and a dev dependency in the example app. But having it here is kinda workaroundish.