Jest中style.setProperty无法设置CSS变量的问题排查

核心问题 #

Jest环境下无法设置/识别CSS变量，具体表现为：

• 调用style.setProperty()设置--xxx格式的CSS变量后，CSSStyleDeclaration中无法看到对应属性
• SCSS文件中定义的CSS变量在Jest测试里不生效，但开发环境完全正常

原因 #

1. JSDOM环境限制：Jest默认使用的JSDOM（模拟浏览器DOM的工具）旧版本对CSS自定义属性（变量）的支持不完善，导致变量无法被正确存储和解析。
2. 样式转换器缺陷：你当前使用的jest-transform-css对CSS变量的处理能力不足，转换样式文件时会丢失变量相关定义。

具体解决办法 #

1. 升级JSDOM版本 #

JSDOM从v16开始对CSS变量提供了良好支持，执行以下命令升级：

npm install jsdom@latest --save-dev
# 或使用yarn
yarn add jsdom@latest -D

2. 替换样式转换器 #

将jest-transform-css替换为支持CSS变量的jest-css-modules-transform：

• 卸载旧转换器：

npm uninstall jest-transform-css --save-dev
# 或 yarn
yarn remove jest-transform-css

• 安装新转换器：

npm install jest-css-modules-transform --save-dev
# 或 yarn
yarn add jest-css-modules-transform -D

• 修改Jest配置（jest.config.js或package.json中的jest字段）：

"moduleNameMapper": {
  "^react-native$": "react-native-web",
  "^.+\\.module\\.(css|sass|scss)$": "jest-css-modules-transform",
  "\\.(css|less|sass|scss)$": "jest-css-modules-transform",
  "\\.(eot|gif|jpg|jpeg|png|svg|ttf)$": "<rootDir>/config/fileMock.js",
  "^\\$components(.*)\\.jsx$": "<rootDir>/src/components$1"
},
"transform": {
  "^.+\\.(css|sass|scss)$": "jest-css-modules-transform"
}

3. 手动Patch CSSStyleDeclaration（应急方案） #

如果升级JSDOM后仍有问题，可在测试启动文件（如src/setupTests.js）中添加以下代码，强制让CSS变量能被CSSStyleDeclaration识别：

// 扩展setProperty方法，支持CSS变量
Object.defineProperty(CSSStyleDeclaration.prototype, 'setProperty', {
  value: function(prop, value) {
    if (prop.startsWith('--')) {
      this[prop] = value;
      // 同步更新_values对象，确保console.log能输出变量
      this._values = {...(this._values || {}), [prop]: value};
      // 更新索引和长度
      const props = Object.keys(this._values);
      this._length = props.length;
      props.forEach((key, idx) => this[idx] = key);
    } else {
      // 执行原生setProperty逻辑
      const originalMethod = Object.getOwnPropertyDescriptor(CSSStyleDeclaration.prototype, 'setProperty').value;
      originalMethod.call(this, prop, value);
    }
  },
  writable: true,
  configurable: true
});

// 扩展getPropertyValue方法，支持读取CSS变量
Object.defineProperty(CSSStyleDeclaration.prototype, 'getPropertyValue', {
  value: function(prop) {
    if (prop.startsWith('--')) {
      return this[prop] || '';
    } else {
      const originalMethod = Object.getOwnPropertyDescriptor(CSSStyleDeclaration.prototype, 'getPropertyValue').value;
      return originalMethod.call(this, prop);
    }
  },
  writable: true,
  configurable: true
});

4. Styled-components专属优化 #

如果你使用styled-components，推荐使用官方测试工具@testing-library/jest-styled-components来更精准地断言CSS变量：

• 安装依赖：

npm install @testing-library/jest-styled-components --save-dev
# 或 yarn
yarn add @testing-library/jest-styled-components -D

• 修改测试用例：

import '@testing-library/jest-styled-components';

it('observes --ion-border-color css variable', () => {
  const w = mount(
    <ThemeProvider >
      <WBordered >Hello</WBordered>
    </ThemeProvider>
  );
  const node = w.find(WBordered);
  node.getDOMNode().style.setProperty('--ion-color', 'black');
  // 直接断言CSS变量值
  expect(node).toHaveStyleRule('--ion-color', 'black');
});

内容的提问来源于stack exchange，提问作者Victor Pudeyev