Skip to main content
Version: 27.1

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.

O 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 arquivos fonte. 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 ships with one transformer out of the box - babel-jest. It will automatically load your project's Babel configuration and transform any file matching the following RegEx: /\.[jt]sx?$/ meaning any .js, .jsx, .ts and .tsx file. In addition, babel-jest will inject the Babel plugin necessary for mock hoisting talked about in ES Module mocking.

If you override the transform configuration option babel-jest will no longer be active, and you'll need to add it manually if you wish to use Babel.

Writing custom transformers#

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

interface SyncTransformer<OptionType = unknown> {
/**
* Indicates if the transformer is capabale of instrumenting the code for code coverage.
*
* If V8 coverage is _not_ active, and this is `true`, Jest will assume the code is instrumented.
* If V8 coverage is _not_ active, and this is `false`. Jest will instrument the code returned by this transformer using Babel.
*/
canInstrument?: boolean;
createTransformer?: (options?: OptionType) => SyncTransformer<OptionType>;
getCacheKey?: (
sourceText: string,
sourcePath: Config.Path,
options: TransformOptions<OptionType>,
) => string;
getCacheKeyAsync?: (
sourceText: string,
sourcePath: Config.Path,
options: TransformOptions<OptionType>,
) => Promise<string>;
process: (
sourceText: string,
sourcePath: Config.Path,
options: TransformOptions<OptionType>,
) => TransformedSource;
processAsync?: (
sourceText: string,
sourcePath: Config.Path,
options: TransformOptions<OptionType>,
) => Promise<TransformedSource>;
}
interface AsyncTransformer<OptionType = unknown> {
/**
* Indicates if the transformer is capabale of instrumenting the code for code coverage.
*
* If V8 coverage is _not_ active, and this is `true`, Jest will assume the code is instrumented.
* If V8 coverage is _not_ active, and this is `false`. Jest will instrument the code returned by this transformer using Babel.
*/
canInstrument?: boolean;
createTransformer?: (options?: OptionType) => AsyncTransformer<OptionType>;
getCacheKey?: (
sourceText: string,
sourcePath: Config.Path,
options: TransformOptions<OptionType>,
) => string;
getCacheKeyAsync?: (
sourceText: string,
sourcePath: Config.Path,
options: TransformOptions<OptionType>,
) => Promise<string>;
process?: (
sourceText: string,
sourcePath: Config.Path,
options: TransformOptions<OptionType>,
) => TransformedSource;
processAsync: (
sourceText: string,
sourcePath: Config.Path,
options: TransformOptions<OptionType>,
) => Promise<TransformedSource>;
}
type Transformer<OptionType = unknown> =
| SyncTransformer<OptionType>
| AsyncTransformer<OptionType>;
interface TransformOptions<OptionType> {
/**
* If a transformer does module resolution and reads files, it should populate `cacheFS` so that
* Jest avoids reading the same files again, improving performance. `cacheFS` stores entries of
* <file path, file contents>
*/
cacheFS: Map<string, string>;
config: Config.ProjectConfig;
/** A stringified version of the configuration - useful in cache busting */
configString: string;
instrument: boolean;
// names are copied from babel: https://babeljs.io/docs/en/options#caller
supportsDynamicImport: boolean;
supportsExportNamespaceFrom: boolean;
supportsStaticESM: boolean;
supportsTopLevelAwait: boolean;
/** the options passed through Jest's config by the user */
transformerConfig: OptionType;
}
type TransformedSource =
| {code: string; map?: RawSourceMap | string | null}
| string;
// Config.ProjectConfig can be seen in in code [here](https://github.com/facebook/jest/blob/v26.6.3/packages/jest-types/src/Config.ts#L323)
// RawSourceMap comes from [`source-map`](https://github.com/mozilla/source-map/blob/0.6.1/source-map.d.ts#L6-L12)

As can be seen, only process or processAsync is mandatory to implement, although we highly recommend implementing getCacheKey as well, so we don't waste resources transpiling the same source file when we can read its previous result from disk. You can use @jest/create-cache-key-function to help implement it.

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.

Exemplos#

TypeScript with type checking#

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

Transforming images to their 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(src, filename, config, options) {
return 'module.exports = ' + JSON.stringify(path.basename(filename)) + ';';
},
};
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',
},
};