The Missing Ingredient for Angular Template Code Coverage and Future-Proof Testing

TL;DR: Turn on Ahead-Of-Time (AOT) compilation for your Angular tests to get accurate template code coverage, faster test execution, production-symmetry, and future-proof tests.

The option is already available for Vitest users and will soon be available for Karma and Jest (experimental builder) users.

😧 What's wrong with JIT?

Whether you are using Karma, Jest, or Vitest, you are probably using Just-In-Time (JIT) compilation for your Angular tests, as until recently, it was the only available option.

The problem is that JIT has a few significant downsides:

• Code coverage is not accurate as the template is not taken into account.
• It is slower as the tests compile the templates on the fly.
• It is not future-proof as Angular has reached the limits of JIT compatibility. By design, some features are simply impossible to implement with JIT.
• It is not symmetrical with the production environment, where AOT is used.

⏰ Why now?

Since Angular 8 and the introduction of IVy, the Angular compiler has started transforming templates into instructions. Among many other benefits, this also meant that code coverage tools could map these instructions to the template and compute the code coverage accordingly.

Theoretically, it has been possible to produce code coverage by running tests with AOT since Angular 8, but the option was not available in Karma or Jest. It has only been possible to enable AOT for testing since Vitest support for Angular was added by the Analog team.

As of November 2024:

• Vitest is the only option that supports AOT compilation.
• There are open PRs for Karma and Jest Experimental Builder to support AOT.

🎁 Other Benefits of AOT Testing

⚡️ Faster Test Execution

Whether you are using JIT or AOT, components will end up being compiled at some point. The main difference is that with AOT, the compilation is done once and can be cached, while with JIT, each test module might end up recompiling components.

This means that even if the transform phase is a bit slower with AOT, the overall test execution time will be faster. The numbers I've seen indicate around 20% faster execution, but this will depend heavily on the structure of your tests and the System Under Test.

👯 Production-Symmetry

We generally want our tests to be as symmetric as possible to the production environment to increase confidence. This is often challenging as it balances against other properties like the speed of the tests, the size of the System Under Test, or predictability.

The interesting aspect of AOT is that it improves production-symmetry without harming other properties. Using AOT, you will gain more confidence and achieve behavior that is closer to production.

🔮 Future-Proof Tests

More importantly, JIT has reached its limits and is becoming a liability for Angular. For instance, some Angular features are simply not supported in JIT (e.g. Deferrable Views). Other potential features from the Angular roadmap, like selectorless components, will probably be impossible to use with JIT.

Actually, since Angular's Signal Inputs (and similar functional APIs), JIT already requires some minimal transforms to work.

By switching to AOT, you are making your tests future-proof, ready to benefit from any innovation, and prepared for whatever the future holds for JIT.

🤔 Drawbacks

🪄 Dynamic Component Constructs Should Be Avoided

By turning on AOT, some techniques that rely on dynamic constructs will break.

For instance, such usage will not work anymore:

// 🛑 This is broken with AOT.
const fixture = render(`<app-button/>`, { imports: [Button] });

function render(template, { imports }) {
  @Component({
    template,
    imports,
  })
  class TestContainer {}

  return TestBed.createComponent(TestContainer);
}

However, bypassing the AOT compilation is still possible (⚠️ for now ️⚠️):

function render(template, { imports }) {
  @Component({
    jit: true,
    template,
    imports,
  })
  class TestContainer {}

  return TestBed.createComponent(TestContainer);
}

My advice is to avoid such constructs as much as possible and prefer creating test-specific components when needed, even though it might be a bit more verbose. In the future, the Angular team could provide alternatives that are both AOT-compatible and less boilerplat-y.

🦦 Shallow Testing is More Challenging

While Shallow Testing should not be your primary testing strategy as it is also less production-symmetric, it is still a useful technique to have in your toolbox.

With AOT, it is currently impossible to override a component's imports using TestBed#overrideComponent.

The workaround is to override the component's dependencies at the module level using the testing framework's API and replace components with their test doubles.

For example, with Vitest:

// app.cmp.spec.ts
vi.mock('./street-map.cmp', async () => {
  return {
    StreetMap: await import('./street-map-fake.cmp').then(
      (m) => m.StreetMapFake
    ),
  };
});

// street-map-fake.cmp.ts
@Component({
  selector: 'app-street-map',
  template: 'Fake Street Map',
})
class StreetMapFake implements StreetMap {
  // ...
}

While this temporary workaround is AOT-compatible, it comes with a cost:

• It is less readable and more verbose.
• "Mocking" (or providing test doubles) at the module level is less granular and can be less predictable.
• It is highly coupled to the testing framework you are using.

For now, I would recommend using JIT for Shallow Tests until TestBed#overrideComponent supports AOT or until the Angular team provides a better alternative. You can achieve this by using a separate configuration for Shallow Tests that use JIT for tests matching a specific pattern like *.jit.spec.ts.

👨🏻‍🍳 Taking Vitest with AOT for a Spin

1. Set up Vitest

• For Angular CLI users, use Analog's schematic.
• For Nx users, choose the vitest option when generating an application or library (available since Nx 20.1.0).

2. Enable AOT

Locate the vite.config.js file and turn on AOT by setting Angular's plugin jit option to false:

export default defineConfig({
  ...
  plugins: [
    angular({ jit: false }),
    ...
  ],
  ...
});

📈 Configure Code Coverage

We have the option to use either istanbul or native v8 for code coverage. For some reason, still under investigation, Vitest coverage remapping fails when using v8. The solution is to fall back to using istanbul instead.

1. Install @vitest/coverage-istanbul

Make sure you install the Vitest Istanbul version that matches Vitest's major version

npm install -D @vitest/coverage-istanbul

2. Choose istanbul as your coverage provider

Update the vite.config.mts to enable coverage using Istanbul:

export default defineConfig({
  ...
  test: {
    ...
    coverage: {
      provider: 'istanbul',
    },
  },
});

🎬 Watch it in Action

You can now run the tests:

nx test my-app --coverage --ui --watch
# or
ng test --coverage --ui --watch

then click on the coverage icon and admire the template's code coverage. 🤯

(you will also find the coverage report in the coverage folder)

Note that the coverage is computed based on the instructions generated by the compiler, which means that:

It will even work for structural directives.

Now, guess what!?

The coverage also works for inline templates! 🚀

☢️ Mind the Code Coverage Trap

While code coverage is a useful tool, it should be used wisely. Keep it as an indicator, not a rigid goal.

Any observed statistical regularity will tend to collapse once pressure is placed upon it for control purposes.

-- Charles Goodhart

In other words, when a measure becomes a target, it ceases to be a good measure.

I'd add that the simplest metrics are often the most misleading.

🚀 What's Next?

Karma users will soon be able to enable AOT with a simple flag.

Jest users have three options:

• Recommended: Migrate to Vitest. (📻 stay tuned as I'll soon be sharing the smoothest migration path)
• Use the experimental builder with AOT.
• Wait for jest-preset-angular AOT support.

Vitest users can enjoy the benefits of AOT right now. 🎉

📚 Additional Resources

• 💻 Demo Repo
• 📝 Angular Ahead-Of-Time (AOT) Compiler Docs
• 📝 Vitest Docs
• 📝 Analog's Docs on Vitest

👨🏻‍🏫 Pragmatic Angular Testing Video Course is Here!

If you are tired of bugs, or high-maintenance tests that break at each refactor, my video course, Pragmatic Angular Testing, is here to help!

Learn practical, reliable testing strategies to keep your Angular apps stable and maintainable. (Now 50% off for a limited time!)