Path mapping

Path mapping — это механизм, который позволяет управлять разрешением модулей и файлов в процессе тестирования JavaScript-приложений с использованием Karma. Он особенно полезен в больших проектах с нестандартной структурой каталогов или при работе с TypeScript, где требуется согласованность путей между кодом приложения и тестами.

Настройка basePath

Первым шагом при работе с path mapping является корректная настройка basePath в конфигурационном файле Karma (karma.conf.js).

module.exports = function(config) {
  config.set({
    basePath: '', // путь относительно корня проекта
    frameworks: ['jasmine'],
    files: [
      'src/**/*.js',
      'test/**/*.spec.js'
    ]
  });
};

basePath задаёт точку отсчёта для всех относительных путей в files, exclude и preprocessors. Правильная установка basePath предотвращает ошибки поиска файлов и облегчает интеграцию с различными сборщиками модулей, такими как Webpack или Rollup.

Использование alias для модулей

Когда структура проекта сложная, удобно использовать alias для сокращения длинных путей импорта. В Karma это реализуется через интеграцию с Webpack.

Пример конфигурации:

const path = require('path');

module.exports = function(config) {
  config.set({
    frameworks: ['jasmine'],
    files: [
      'test/**/*.spec.js'
    ],
    preprocessors: {
      'test/**/*.spec.js': ['webpack']
    },
    webpack: {
      resolve: {
        alias: {
          '@components': path.resolve(__dirname, 'src/components/'),
          '@utils': path.resolve(__dirname, 'src/utils/')
        },
        extensions: ['.js', '.ts']
      }
    }
  });
};

Ключевые моменты:

alias позволяет использовать короткие пути в тестах, например:
```
import Button from '@components/Button';
```
Совместимость с TypeScript требует дополнительной настройки tsconfig.json для согласования путей:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@components/*": ["src/components/*"],
      "@utils/*": ["src/utils/*"]
    }
  }
}

Маппинг путей без Webpack

Иногда использование Webpack нежелательно. Karma поддерживает настройку proxies, которая позволяет подменять URL-файлы, используемые в браузере для тестов.

module.exports = function(config) {
  config.set({
    files: [
      'dist/**/*.js',
      'test/**/*.spec.js'
    ],
    proxies: {
      '/@components/': '/base/dist/components/',
      '/@utils/': '/base/dist/utils/'
    }
  });
};

/base/ — специальный префикс Karma, который указывает на basePath.
Подмена путей через proxies полезна при работе с библиотеками, собранными отдельно, или при интеграции с CI/CD.

Совместимость с TypeScript и модульными системами

Path mapping особенно востребован при работе с TypeScript, потому что TypeScript поддерживает paths в tsconfig.json. Karma же напрямую использует результат компиляции. Чтобы обеспечить корректное разрешение модулей, необходимо:

Настроить tsconfig.json с правильными alias.
Применить karma-webpack или karma-typescript, чтобы тесты понимали alias.
Проверить, что basePath совпадает с корнем проекта или с baseUrl TypeScript.

Пример для karma-typescript:

module.exports = function(config) {
  config.set({
    frameworks: ['jasmine', 'karma-typescript'],
    files: [
      { pattern: 'src/**/*.ts' },
      { pattern: 'test/**/*.spec.ts' }
    ],
    preprocessors: {
      '**/*.ts': ['karma-typescript']
    },
    karmaTypescriptConfig: {
      tsconfig: './tsconfig.json',
      bundlerOptions: {
        resolve: {
          alias: {
            '@components': './src/components',
            '@utils': './src/utils'
          }
        }
      }
    }
  });
};

Частые ошибки при настройке path mapping

Неправильный basePath — файлы не загружаются, тесты не запускаются.
Несогласованные alias между TypeScript и Karma — импорты в тестах ломаются.
Отсутствие расширений файлов в resolve.extensions — некоторые импорты остаются необнаруженными.
Конфликт с другими плагинами — особенно с karma-webpack и karma-typescript, если их конфигурации дублируют alias.