Skip to main content
Version: Next

Transformação de Código

O Jest roda o código do seu projeto como JavaScript, mas se você usa alguma sintaxe não suportada pelo Node.js nativamente (como JSX, tipos do TypeScript, templates do Vue e etc.), então você vai precisar transformar esse código em JavaScript puro, de maneira similar ao que você faria quando construindo para navegadores.

Jest suporta isso através da opção de configuração transform.

Um transformador é um módulo que fornece uma função síncrona para transformar os arquivos de origem. Por exemplo, se você quisesse poder utilizar uma nova funcionalidade da linguagem nos seus módulos ou testes que ainda não é suportada pelo Node, você pode adicionar um de muitos compiladores que compilam uma versão futura do JavaScript para uma atual.

O Jest vai armazenar em cache o resultado de uma transformação e tentar invalidar aquele resultado com base em vários fatores, como a fonte do arquivo que está sendo transformado e a alteração de configuração.

Defaults

Jest vem com um transformador nativo babel-jest. Ele carregará a configuração Babel do seu projeto e transformará qualquer arquivo correspondente ao /\.[jt]sx?$/ RegExp (em outras palavras, qualquer . s, .jsx, .ts ou .tsx arquivo). In addition, babel-jest will inject the Babel plugin necessary for mock hoisting talked about in ES Module mocking.

tip

Remember to include the default babel-jest transformer explicitly, if you wish to use it alongside with additional code preprocessors:

"transform": {
"\\.[jt]sx?$": "babel-jest",
"\\.css$": "some-css-transformer",
}

Writing custom transformers

You can write your own transformer. The API of a transformer is as follows:

interface TransformOptions<TransformerConfig = unknown> {
supportsDynamicImport: boolean;
supportsExportNamespaceFrom: boolean;
supportsStaticESM: boolean;
supportsTopLevelAwait: boolean;
instrument: boolean;
/** Cached file system which is used by `jest-runtime` to improve performance. */
cacheFS: Map<string, string>;
/** Jest configuration of currently running project. */
config: ProjectConfig;
/** Stringified version of the `config` - useful in cache busting. */
configString: string;
/** Transformer configuration passed through `transform` option by the user. */
transformerConfig: TransformerConfig;
}

type TransformedSource = {
code: string;
map?: RawSourceMap | string | null;
};

interface SyncTransformer<TransformerConfig = unknown> {
canInstrument?: boolean;

getCacheKey?: (
sourceText: string,
sourcePath: string,
options: TransformOptions<TransformerConfig>,
) => string;

getCacheKeyAsync?: (
sourceText: string,
sourcePath: string,
options: TransformOptions<TransformerConfig>,
) => Promise<string>;

process: (
sourceText: string,
sourcePath: string,
options: TransformOptions<TransformerConfig>,
) => TransformedSource;

processAsync?: (
sourceText: string,
sourcePath: string,
options: TransformOptions<TransformerConfig>,
) => Promise<TransformedSource>;
}

interface AsyncTransformer<TransformerConfig = unknown> {
canInstrument?: boolean;

getCacheKey?: (
sourceText: string,
sourcePath: string,
options: TransformOptions<TransformerConfig>,
) => string;

getCacheKeyAsync?: (
sourceText: string,
sourcePath: string,
options: TransformOptions<TransformerConfig>,
) => Promise<string>;

process?: (
sourceText: string,
sourcePath: string,
options: TransformOptions<TransformerConfig>,
) => TransformedSource;

processAsync: (
sourceText: string,
sourcePath: string,
options: TransformOptions<TransformerConfig>,
) => Promise<TransformedSource>;
}

type Transformer<TransformerConfig = unknown> =
| SyncTransformer<TransformerConfig>
| AsyncTransformer<TransformerConfig>;

type TransformerCreator<
X extends Transformer<TransformerConfig>,
TransformerConfig = unknown,
> = (transformerConfig?: TransformerConfig) => X;

type TransformerFactory<X extends Transformer> = {
createTransformer: TransformerCreator<X>;
};
note

As definições acima foram encurtadas por brevidade. O código completo pode ser encontrado no repositório Jest no GitHub (lembre-se de escolher a tag/commit correta para a sua versão do Jest).

Há algumas maneiras de importar código para o Jest - usando Common JS (require) ou ECMAScript Módulos (import - que existem em versões estáticas e dinâmicas). Jest passa os arquivos através da transformação de código na demanda (por exemplo, quando um require ou import é avaliado). Este processo, também conhecido como "transpilação", pode acontecer sincronizadamente (no caso de require), ou asynchronously (no caso de import ou import(), o último dos quais também funciona com módulos Common JS). Por esta razão, a interface expõe os dois pares de métodos para processos assíncronos e síncronos: process{Async} e getCacheKey{Async}. O último é chamado para descobrir se precisamos chamar o process{Async}. Uma vez que a transformação assíncrona pode acontecer sincronizadamente sem issue, é possível que o caso assíncrono "volte" para a variante de sincronização, mas não vice-versa.

Então, se sua base de código é ESM implementando, apenas as variantes assíncronas é suficiente. Caso contrário, se qualquer código for carregado através de require (incluindo createRequire de dentro da ESM), então você precisa implementar a variante síncrona. Esteja ciente de que node_modules não é transpilado com configuração padrão.

Semirelacionada a isto são os suportes sinalizadores que passamos (veja CallerTransformOptions acima), mas eles devem ser usados dentro da transformação para descobrir se ele deve retornar ESM ou CJS, e não tem impacto direto na sync vs async.

Embora não seja necessário, nós altamente recomendamos implementando getCacheKey também, portanto, não desperdiçamos recursos que se transpilam quando poderíamos ter lido o resultado anterior do disco. You can use @jest/create-cache-key-function to help implement it.

Em vez de ter seu transformador personalizado implementando a interface Transformer diretamente, você pode optar por exportar createTransformer, uma função de fábrica para criar dinamicamente transformadores. Isso permite ter uma configuração de transformador na sua configuração do jest.

Note that ECMAScript module support is indicated by the passed in supports* options. Specifically supportsDynamicImport: true means the transformer can return import() expressions, which is supported by both ESM and CJS. If supportsStaticESM: true it means top level import statements are supported and the code will be interpreted as ESM and not CJS. See Node's docs for details on the differences.

tip

Certifique-se de que processs{Async} o método retorna o mapa de origem juntamente com o código transformado, portanto, é possível relatar informação de linha com precisão na cobertura de código e erros de teste. Inline source maps also work but are slower.

Durante o desenvolvimento de um transformador pode ser útil executar Jest com --no-cache para frequentemente delete cache.

Exemplos

TypeScript com verificação de tipo

While babel-jest by default will transpile TypeScript files, Babel will not verify the types. If you want that you can use ts-jest.

Transformando imagens em seu path

Importing images is a way to include them in your browser bundle, but they are not valid JavaScript. One way of handling it in Jest is to replace the imported value with its filename.

fileTransformer.js
const path = require('path');

module.exports = {
process(sourceText, sourcePath, options) {
return {
code: `module.exports = ${JSON.stringify(path.basename(sourcePath))};`,
};
},
};
jest.config.js
module.exports = {
transform: {
'\\.(jpg|jpeg|png|gif|eot|otf|webp|svg|ttf|woff|woff2|mp4|webm|wav|mp3|m4a|aac|oga)$':
'<rootDir>/fileTransformer.js',
},
};