bug: Jest 30 Support: Documentation Claims Support but Version Check Blocks It

[michaelsouellette]

Prerequisites

• I have read the Contributing Guidelines.
• I agree to follow the Code of Conduct.
• I have searched for existing issues that already report this problem, without success.

Stencil Version

+4.42.1

Current Behavior

The Stencil documentation for v4.43.0 states that Jest 30+ is supported (https://stenciljs.com/docs/testing/jest), however, when running tests with Jest 30.2.0, Stencil's test runner throws an error requiring Jest 29 or lower.

This creates a discrepancy between the documentation and the actual implementation, preventing projects from upgrading to Jest 30 while using Stencil.

Actual Behavior

Stencil throws the following error and refuses to run tests:

[13:37.3]  @stencil/core
[13:37.5]  v4.43.0 👒

[ ERROR ]  Please install supported versions of dev dependencies with either npm or yarn.
           npm install --save-dev @types/jest@29 jest@29

The test runner exits with a non-zero status code without running any tests.

Root Cause Analysis

The error appears to be coming from hardcoded version checking in Stencil's testing module that only accepts Jest 27-29, despite the documentation being updated to reflect Jest 30+ support.

Impact

This issue is blocking:

• Projects using Nx (which defaults to Jest 30 in recent versions)
• Projects that need Jest 30 features or bug fixes
• Migration paths from older Stencil versions that expect documentation to be accurate

Workarounds Attempted

1. ✅ Added explicit testing configuration to stencil.config.ts
2. ✅ Used Stencil CLI directly (not through Nx executors)
3. ✅ Configured Jest preprocessor correctly
4. ✅ Updated to latest Stencil version (4.43.0)
5. ❌ None of these resolve the version check error

The only workaround is downgrading to Jest 29, which may break other dependencies in modern monorepos.

Expected Behavior

Based on the documentation at https://stenciljs.com/docs/testing/jest, Jest 30+ should be fully supported. Tests should run without version compatibility errors.

Proposed Solution

1. Update the version checking code in @stencil/core/testing to accept Jest 30+
2. Add Jest 30 to CI testing matrix to prevent future regressions
3. If Jest 30 support is not yet ready, update documentation to reflect accurate version requirements

System Info

- **@stencil/core**: v4.43.0 (also reproduced in v4.42.1)
- **jest**: v30.2.0
- **@types/jest**: v30.0.0
- **Node**: v20+ (latest LTS)
- **OS**: macOS (also reproducible on other platforms)

Steps to Reproduce

1. Install Stencil 4.43.0 and Jest 30.2.0:

   npm install @stencil/core@4.43.0 jest@30.2.0 @types/jest@30.0.0

2. Create a basic stencil.config.ts with testing configuration:

   import { Config } from '@stencil/core';
   
   export const config: Config = {
     namespace: 'test',
     testing: {
       browserHeadless: 'shell',
       testPathIgnorePatterns: ['/node_modules/', '/dist/'],
       coveragePathIgnorePatterns: ['/node_modules/', '/dist/'],
       transform: {
         '^.+\\.(ts|tsx)$': ['@stencil/core/testing/jest-preprocessor', {}]
       },
       moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json'],
       testRegex: '(/__tests__/.*|\\.(test|spec))\\.(tsx?|jsx?)$'
     }
   };

3. Run Stencil tests:

   stencil test --spec

Code Reproduction URL

https://github.com/michaelsouellette/stencil-jest-30-reproduction

Additional Information

Additional Context

This issue has been reproduced across multiple Stencil versions (4.42.1, 4.43.0) suggesting the documentation was updated in anticipation of support but the actual implementation wasn't completed.

The documentation should either:

• Be corrected to show Jest 29 as the maximum supported version, OR
• The version checking code should be updated to allow Jest 30+

References

• Documentation: https://stenciljs.com/docs/testing/jest
• Jest 30 Release: https://jestjs.io/blog/2024/11/14/jest-30
• Similar reported issues: (add any related issues if found)

[johnjenkins]

hey @michaelsouellette - and thanks for raising.

The cited documentation at https://stenciljs.com/docs/testing/jest provides jest 30 support via a separate package - https://www.npmjs.com/package/jest-stencil-runner

The hard baked Jest version within Stencil core is a known (and difficult to untangle) issue which will be fixed in v5 by removing all integrated testing within Stencil - read more at #6584. If you continue using the aforementioned jest-30 package - you may have to force (via overrides?) the jest version for now.

My strong suggestion however would be for you to migrate your spec style tests to stencil/vitest (https://github.com/stenciljs/vitest) - this is completely decoupled, more flexible, modern and ultimately better all-round testing solution