Plugins do Modo Watch

Tradução Beta Não Oficial

Esta página foi traduzida por PageTurner AI (beta). Não é oficialmente endossada pelo projeto. Encontrou um erro? Reportar problema →

O sistema de plugins do modo watch no Jest permite conectar-se a partes específicas do framework e definir prompts no menu de watch que executam código ao pressionar teclas. Combinados, esses recursos permitem criar experiências interativas personalizadas para seu fluxo de trabalho.

Interface do Plugin do Watch

class MyWatchPlugin {
  // Add hooks to Jest lifecycle events
  apply(jestHooks) {}

  // Get the prompt information for interactive plugins
  getUsageInfo(globalConfig) {}

  // Executed when the key from `getUsageInfo` is input
  run(globalConfig, updateConfigAndRun) {}
}

Conectando-se ao Jest

Para conectar seu plugin ao Jest, adicione seu caminho em watchPlugins na configuração do Jest:

jest.config.js

module.exports = {
  // ...
  watchPlugins: ['path/to/yourWatchPlugin'],
};

Plugins personalizados podem adicionar hooks aos eventos do Jest. Esses hooks podem ser implementados com ou sem uma tecla interativa no menu do modo watch.

apply(jestHooks)

Os hooks do Jest podem ser anexados implementando o método apply. Ele recebe um argumento jestHooks que permite conectar o plugin a partes específicas do ciclo de execução de testes.

class MyWatchPlugin {
  apply(jestHooks) {}
}

Abaixo estão os hooks disponíveis no Jest:

jestHooks.shouldRunTestSuite(testSuiteInfo)

Retorna um booleano (ou Promise<boolean> para operações assíncronas) indicando se um teste deve ser executado.

Por exemplo:

class MyWatchPlugin {
  apply(jestHooks) {
    jestHooks.shouldRunTestSuite(testSuiteInfo => {
      return testSuiteInfo.testPath.includes('my-keyword');
    });

    // or a promise
    jestHooks.shouldRunTestSuite(testSuiteInfo => {
      return Promise.resolve(testSuiteInfo.testPath.includes('my-keyword'));
    });
  }
}

jestHooks.onTestRunComplete(results)

Chamado ao final de cada execução de testes, recebendo os resultados como argumento.

Por exemplo:

class MyWatchPlugin {
  apply(jestHooks) {
    jestHooks.onTestRunComplete(results => {
      this._hasSnapshotFailure = results.snapshot.failure;
    });
  }
}

jestHooks.onFileChange({projects})

Chamado sempre que ocorre uma alteração no sistema de arquivos

• projects: Array<config: ProjectConfig, testPaths: Array<string>: Inclui todos os caminhos de testes monitorados pelo Jest.

Por exemplo:

class MyWatchPlugin {
  apply(jestHooks) {
    jestHooks.onFileChange(({projects}) => {
      this._projects = projects;
    });
  }
}

Integração com o Menu Watch

Plugins também podem adicionar ou substituir funcionalidades no menu através de um par tecla/prompt no método getUsageInfo e um método run para executar a ação.

getUsageInfo(globalConfig)

Para adicionar uma tecla ao menu, implemente getUsageInfo retornando uma tecla e o prompt:

class MyWatchPlugin {
  getUsageInfo(globalConfig) {
    return {
      key: 's',
      prompt: 'do something',
    };
  }
}

Isso adicionará uma linha no menu do modo watch (› Press s to do something.)

Watch Usage
 › Press p to filter by a filename regex pattern.
 › Press t to filter by a test name regex pattern.
 › Press q to quit watch mode.
 › Press s to do something. // <-- This is our plugin
 › Press Enter to trigger a test run.

"message": "nota"

Se a tecla do seu plugin já existir como padrão, seu plugin substituirá essa tecla.

run(globalConfig, updateConfigAndRun)

Para processar eventos de teclas retornadas por getUsageInfo, implemente o método run. Ele retorna uma Promise<boolean> resolvida quando o plugin devolve o controle ao Jest. O boolean indica se os testes devem ser reexecutados após retomar o controle.

• globalConfig: Representa a configuração global atual do Jest

• updateConfigAndRun: Permite disparar uma execução de testes durante a operação do plugin.

class MyWatchPlugin {
  run(globalConfig, updateConfigAndRun) {
    // do something.
  }
}

"message": "nota"

Se você chamar updateConfigAndRun, seu método run não deve resolver para um valor verdadeiro para evitar execuções duplicadas.

Chaves de configuração autorizadas

Por questões de estabilidade e segurança, apenas parte das chaves de configuração podem ser atualizadas com updateConfigAndRun. A lista permitida atual é:

• bail

• changedSince

• collectCoverage

• collectCoverageFrom

• coverageDirectory

• coverageReporters

• notify

• notifyMode

• onlyFailures

• reporters

• testNamePattern

• testPathPatterns

• updateSnapshot

• verbose

Personalização

Os plugins podem ser personalizados através da sua configuração do Jest.

jest.config.js

module.exports = {
  // ...
  watchPlugins: [
    [
      'path/to/yourWatchPlugin',
      {
        key: 'k', // <- your custom key
        prompt: 'show a custom prompt',
      },
    ],
  ],
};

Nomes de configuração recomendados:

• key: Modifica a chave do plugin.

• prompt: Permite personalizar o texto do prompt no plugin.

Se o usuário fornecer uma configuração personalizada, ela será passada como argumento para o construtor do plugin.

class MyWatchPlugin {
  constructor({config}) {}
}

Escolhendo uma boa tecla

O Jest permite que plugins de terceiros substituam algumas teclas de funcionalidades internas, mas não todas. Especificamente, as seguintes teclas não podem ser substituídas:

• c (limpa padrões de filtro)

• i (atualiza snapshots não correspondentes interativamente)

• q (sai)

• u (atualiza todos os snapshots não correspondentes)

• w (exibe uso do modo watch / ações disponíveis)

As seguintes teclas para funcionalidades internas podem ser substituídas:

• p (padrão de nome de arquivo de teste)

• t (padrão de nome de teste)

Qualquer tecla não utilizada por funcionalidades internas pode ser reivindicada, como esperado. Evite usar teclas difíceis de acessar em vários teclados (ex: é, €), ou que não sejam visíveis por padrão (ex: muitos teclados Mac não mostram dicas visuais para caracteres como |, \, [, etc.)

Quando ocorre um conflito

Se seu plugin tentar substituir uma tecla reservada, o Jest exibirá um erro com mensagem descritiva, como:

Watch plugin YourFaultyPlugin attempted to register key `q`, that is reserved internally for quitting watch mode. Please change the configuration key for this plugin.

Plugins de terceiros também são proibidos de substituir teclas já reservadas por outros plugins presentes anteriormente na lista de plugins configurados (configuração do array watchPlugins). Quando isso ocorre, você também receberá uma mensagem de erro que tenta ajudar na correção:

Watch plugins YourFaultyPlugin and TheirFaultyPlugin both attempted to register key `x`. Please change the key configuration for one of the conflicting plugins to avoid overlap.