diff --git a/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/helpers/list-files.mdx b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/helpers/list-files.mdx new file mode 100644 index 00000000..a8fe9920 --- /dev/null +++ b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/helpers/list-files.mdx @@ -0,0 +1,71 @@ +import { History } from '@site/src/components/History'; + +# đŸ—„ïž List Files + +Retorna todos os arquivos em um diretĂłrio (independente de sua profundidade) ou o prĂłprio arquivo. + +Suporte para uso via CLI.], + }, + ]} +/> + +## CLI + +Exibe todos os arquivos retornados no terminal, sem executar os testes. + +```sh +npx poku --list-files +``` + +```sh +npx poku ./test --list-files +``` + +```sh +npx poku ./packages/**/test --list-files +``` + +```sh +npx poku ./test/unit ./test/e2e --list-files +``` + +- VocĂȘ pode usar as flags `--filter` e `--exclude` e incluir mĂșltiplos caminhos. + +:::note + +Os arquivos retornados pelo `--list-files` nĂŁo refletem os caminhos exibidos pelo `--debug`: + +- **`--debug`:** os caminhos a serem pesquisados. +- **`--list-files`:** os caminhos encontrados. + +::: + +:::tip +Se vocĂȘ passar flags diferentes de `--filter` e `--exclude`, elas serĂŁo ignoradas. +::: + +## API + +> `listFiles(diretĂłrioDeDestino: string, configs?: ListFilesConfigs)` + +```ts +import { listFiles } from 'poku'; + +await listFiles('algum-diretĂłrio'); +``` + +- VocĂȘ pode usar as opçÔes `filter` e `exclude`, assim como sĂŁo usadas no mĂ©todo **`poku`**. + +:::info + +Para compilar testes usando `listFiles` com **TypeScript**, vocĂȘ pode precisar instalar o **@types/node**: + +```bash +npm i -D @types/node +``` + +::: diff --git a/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/helpers/log.mdx b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/helpers/log.mdx new file mode 100644 index 00000000..8b43fd55 --- /dev/null +++ b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/helpers/log.mdx @@ -0,0 +1,15 @@ +# 📝 Log + +Como por padrĂŁo o **Poku** sĂł exibe saĂ­das geradas por ele mesmo, este auxiliar permite usar uma alternativa ao `console.log` com o executor do **Poku**. + +```ts +import { log } from 'poku'; + +log('o Poku irĂĄ exibir isso'); + +console.log('O poku nĂŁo irĂĄ exibir isso'); +``` + +:::tip +Precisa depurar? Basta usar a opção [`debug`](/docs/documentation/poku/options/debug) do `poku`. +::: diff --git a/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/helpers/processes/get-pids.mdx b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/helpers/processes/get-pids.mdx new file mode 100644 index 00000000..c70da1e8 --- /dev/null +++ b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/helpers/processes/get-pids.mdx @@ -0,0 +1,73 @@ +--- +tags: [processes, ports, debug] +--- + +# Buscando PIDs + +Retorna os IDs dos processos usados pelas portas e intervalos de portas especificados. + +## getPIDs + +Retorna todos os IDs dos processos usados pelas portas especificadas. + +> `getPIDs(porta: number | number[])` + +- Requer `lsof` para **Unix** e `netstat` para **Windows**. + +```ts +import { getPIDs } from 'poku'; + +await getPIDs(4000); +``` + +```ts +await getPIDs([4000, 4001]); +``` + +--- + +## getPIDs.range + +Retorna todos os IDs dos processos usados pelo intervalo de portas especificado. + +> `getPIDs.range(iniciaEm: number, terminaEm: number)` + +- Requer `lsof` para **Unix** e `netstat` para **Windows**. + +```ts +import { getPIDs } from 'poku'; + +await getPIDs.range(4000, 4100); +``` + +--- + +:::tip + +Se o seu ambiente nĂŁo incluir o `lsof` por padrĂŁo: + +**macOS (Homebrew)** + +```sh +brew install lsof +``` + +**Debian, Ubuntu, etc.** + +```sh +sudo apt-get install lsof +``` + +**Arch Linux, etc.** + +```sh +sudo pacman -S lsof +``` + +**Alpine Linux, etc.** + +```sh +apk add lsof +``` + +::: diff --git a/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/helpers/processes/kill.mdx b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/helpers/processes/kill.mdx new file mode 100644 index 00000000..35ab1022 --- /dev/null +++ b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/helpers/processes/kill.mdx @@ -0,0 +1,144 @@ +--- +sidebar_position: 1 +tags: [processes, ports] +--- + +# Encerrando Processos + +Encerra as portas especificadas, intervalos de portas e IDs de processos. + +## kill.port + +> `kill.port(porta: number | number[])` + +Encerra as portas especificadas + +- Requer `lsof` para **Unix** e `netstat` para **Windows**. + +### CLI + +Encerra as portas especificadas antes de executar a suĂ­te de testes. + +```bash +npx poku --kill-port="4000" caminhoDoTeste +``` + +TambĂ©m, encerrando mĂșltiplas portas: + +```bash +npx poku --kill-port="4000,4001" caminhoDoTeste +``` + +### API + +```ts +import { kill } from 'poku'; + +await kill.port(4000); +``` + +TambĂ©m, encerrando mĂșltiplas portas: + +```ts +await kill.port([4000, 4001]); +``` + +--- + +## kill.range + +> `kill.range(iniciaEm: number, terminaEm: number)` + +Encerra o intervalo de portas especificado. + +- Requer `lsof` para **Unix** e `netstat` para **Windows**. + +### CLI + +Encerra o intervalo de portas especificado antes de executar a suĂ­te de testes. + +```bash +npx poku --kill-range="4000-4100" caminhoDoTeste +``` + +TambĂ©m, encerrando mĂșltiplos intervalos de portas: + +```bash +npx poku --kill-range="4000-4100,5000-5100" caminhoDoTeste +``` + +### API + +```ts +import { kill } from 'poku'; + +await kill.range(4000, 4100); +``` + +--- + +## kill.pid + +> `kill.pid(PID: number | number[])` + +Encerra os processos especificados. + +### CLI + +Encerra os processos especificados antes de executar a suĂ­te de testes + +```bash +npx poku --kill-pid="100" caminhoDoTeste +``` + +TambĂ©m, encerrando mĂșltiplos processos: + +```bash +npx poku --kill-pid="100,200" caminhoDoTeste +``` + +### API + +```ts +import { kill } from 'poku'; + +await kill.pid(100); +``` + +TambĂ©m, encerrando mĂșltiplos processos: + +```ts +await kill.pid([100, 200]); +``` + +--- + +:::tip + +Se o seu ambiente nĂŁo incluir o `lsof` por padrĂŁo: + +**macOS (Homebrew)** + +```sh +brew install lsof +``` + +**Debian, Ubuntu, etc.** + +```sh +sudo apt-get install lsof +``` + +**Arch Linux, etc.** + +```sh +sudo pacman -S lsof +``` + +**Alpine Linux, etc.** + +```sh +apk add lsof +``` + +::: diff --git a/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/helpers/processes/wait-for-expected-result.mdx b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/helpers/processes/wait-for-expected-result.mdx new file mode 100644 index 00000000..471593a1 --- /dev/null +++ b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/helpers/processes/wait-for-expected-result.mdx @@ -0,0 +1,154 @@ +--- +sidebar_position: 3 +tags: [flakey, containers] +--- + +import { FAQ } from '@site/src/components/FAQ'; + +# Aguardando por Resultados Esperados + +Semelhante ao `assert`, mas em vez de retornar um erro na comparação, ele tentarĂĄ novamente atĂ© obter sucesso ou exceder o tempo limite. + +> Espera atĂ© que conexĂ”es, serviços externos estejam prontos ou que um resultado especĂ­fico de um mĂ©todo esteja disponĂ­vel antes de iniciar os testes. + +## waitForExpectedResult + +```ts +import { waitForExpectedResult } from 'poku'; + +await waitForExpectedResult(() => true, true, { + delay: 0, + interval: 100, + timeout: 60000, + strict: false, +}); +``` + +
+ + + +```ts +export type WaitForExpectedResultOptions = { + /** + * Intervalo de repetição em milissegundos + * + * --- + * + * @default 100 + */ + interval?: number; + /** + * Tempo limite em milissegundos + * + * --- + * + * @default 60000 + */ + timeout?: number; + /** + * Atrasa o inĂ­cio e o fim pelo nĂșmero definido de milissegundos. + * + * --- + * + * @default 0 + */ + delay?: number; + /** + * Garante comparaçÔes estritas. + * + * - Para usuĂĄrios do **Bun**, essa opção nĂŁo Ă© necessĂĄria. + * + * --- + * + * @default false + */ + strict?: boolean; +}; +``` + + + +
+ +## Exemplos + +Aguardando até a conexão com o banco de dados retornar `true`: + +```ts +import { waitForExpectedResult } from 'poku'; +import { db } from './db.js'; + +await waitForExpectedResult(() => db.connect(), true); +// await waitForExpectedResult(async () => await db.connect(), true); +``` + +
+ +Aguardando até que a conexão com o banco de dados não lance uma exceção: + +```ts +import { waitForExpectedResult } from 'poku'; +import { db } from './db.js'; + +await waitForExpectedResult(async () => { + try { + await db.connect(); + return true; + } catch {} +}, true); +``` + +
+ +Aguardando por uma conexĂŁo com o banco de dados de um contĂȘiner antes de executar toda a suĂ­te de testes e parando o contĂȘiner ao finalizar: + +> Exemplo de _API_ do **Poku**. + +```ts +import { poku, docker, waitForExpectedResult, exit } from 'poku'; +import { db } from './db.js'; + +// Carrega o docker-compose.yml +const compose = docker.compose(); + +// Inicia o contĂȘiner +await compose.up(); + +// Aguardando pelo banco de dados +await waitForExpectedResult(async () => { + try { + await db.connect(); + return true; + } catch {} +}, true); + +// Inicia a suĂ­te de testes +const result = await poku('./test/integration', { + noExit: true, +}); + +// Finaliza o contĂȘiner +await compose.down(); + +// Mostra os resultados dos testes e encerra o processo com o cĂłdigo de saĂ­da dos testes. +exit(result); +``` + +
+ +EntĂŁo: + +```sh +node run.test.js +``` + +```sh +npx tsx run.test.ts +``` + +
+ +:::tip +[Veja um exemplo usando o **Dockerfile**.](/docs/documentation/helpers/containers#dockerfile) +::: diff --git a/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/helpers/processes/wait-for-port.mdx b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/helpers/processes/wait-for-port.mdx new file mode 100644 index 00000000..7183da2b --- /dev/null +++ b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/helpers/processes/wait-for-port.mdx @@ -0,0 +1,123 @@ +--- +sidebar_position: 2 +tags: [flakey, containers] +--- + +import { FAQ } from '@site/src/components/FAQ'; + +# Aguardando Portas + +Aguarda as portas especificadas se tornarem ativas. + +## waitForPort + +```ts +import { waitForPort } from 'poku'; + +await waitForPort(3000, { + delay: 0, + interval: 100, + timeout: 60000, + host: 'localhost', +}); +``` + +
+ + + +```ts +export type WaitForPortOptions = { + /** + * Intervalo de tentativa em milissegundos + * + * --- + * + * @default 100 + */ + interval?: number; + /** + * Tempo limite em milissegundos + * + * --- + * + * @default 60000 + */ + timeout?: number; + /** + * Atrasa o inĂ­cio e o fim pelo nĂșmero definido de milissegundos. + * + * --- + * + * @default 0 + */ + delay?: number; + /** + * Host para verificar a porta. + * + * --- + * + * @default "localhost" + */ + host?: string; +}; +``` + + + +
+ +## Exemplos + +### Aguardando MĂșltiplas Portas + +```ts +import { waitForPort } from 'poku'; + +await Promise.all([ + waitForPort(3000), + waitForPort(4000), + waitForPort(5000), + waitForPort(6000), +]); +``` + +### Aguardando um Serviço de Container na Porta 3000 + +```ts +import { docker, waitForPort } from 'poku'; + +// highlight-start +const compose = docker.compose(); + +await compose.up(); +// highlight-end +await waitForPort(3000, { delay: 100 }); + +// highlight-start +const res = await fetch('http://localhost:3000'); +// highlight-end + +/** + * Os testes vĂȘm aqui đŸ§Ș + */ + +// highlight-start +await compose.down(); +// highlight-end +``` + +
+ +:::tip + +O **Poku** expĂ”e um auxiliar `sleep` mĂ­nimo que apenas espera por milissegundos, alĂ©m do `waitForPort`: + +```ts +import { sleep } from 'poku'; + +// Aguarda por 1 segundo +await sleep(1000); +``` + +::: diff --git a/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/helpers/skip.mdx b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/helpers/skip.mdx index f962f9a9..843eb1b0 100644 --- a/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/helpers/skip.mdx +++ b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/helpers/skip.mdx @@ -32,20 +32,20 @@ Imagine que um teste especĂ­fico nĂŁo funcione em um _SO_ especĂ­fico: ```ts import { test, skip } from 'poku'; -// destaca-inĂ­cio +// highlight-start import { platform } from 'node:process'; const isWindows = platform === 'win32'; -// destaca-fim +// highlight-end if (isWindows) skip('Pulando devido Ă  incompatibilidade com o Windows'); // Executa testes normalmente em outros sistemas operacionais -// destaca-inĂ­cio +// highlight-start test(() => { // ... }); -// destaca-fim +// highlight-end ``` :::note diff --git a/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/helpers/startScript.mdx b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/helpers/startScript.mdx index dc42cf1c..a3c01b3f 100644 --- a/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/helpers/startScript.mdx +++ b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/helpers/startScript.mdx @@ -132,7 +132,7 @@ kill -9 PID ```ts type StartScriptOptions = { /** - * - Por padrĂŁo, Isso serĂĄ resolvido na primeira saĂ­da do console + * - Por padrĂŁo, serĂĄ resolvido na primeira saĂ­da do console * - Definindo uma string: ele aguardarĂĄ uma string especĂ­fica na saĂ­da do console para resolver * - Definindo um nĂșmero: ele aguardarĂĄ o tempo em milissegundos para resolver * @@ -155,7 +155,7 @@ type StartScriptOptions = { */ verbose?: boolean; /** - * Especifique um caminho de destino para iniciar o processo + * Especifica um caminho de destino para iniciar o processo * * @default "./" */ diff --git a/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/helpers/startService.mdx b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/helpers/startService.mdx new file mode 100644 index 00000000..39e1ecbd --- /dev/null +++ b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/helpers/startService.mdx @@ -0,0 +1,160 @@ +--- +sidebar_position: 8 +tags: [background, server, service] +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import { FAQ } from '@site/src/components/FAQ'; +import Success from '@site/static/img/success.svg'; + +# 🔁 Start Service + +Execute seus serviços em um processo em segundo plano e teste-os đŸ§‘đŸ»â€đŸ”Ź + +> startService(caminhoDoArquivo: string, opçÔes?: StartServiceOptions); + +O `startService` executa um arquivo diretamente e mantĂ©m-o em execução em um processo em segundo plano atĂ© que vocĂȘ o libere. + +
+
+ + Permite que **cookies** persistam (_ou nĂŁo_) đŸȘ +
+
+ + + O **Poku** permite que vocĂȘ utilize o cliente HTTP que quiser, como o + [**Axios**](https://github.com/axios/axios), o fetch nativo e outros ✹ + +
+
+ + + nĂŁo Ă© necessĂĄrio exportar seu app, server ou qualquer serviço, basta + executĂĄ-lo como estĂĄ 🚀 + +
+
+ + + Pare de alterar seu cĂłdigo devido Ă s regras do teste, vocĂȘ criou seu + cĂłdigo, nĂŁo o **Poku** đŸ©” + +
+
+ +
+ +[Veja exemplos prĂĄticos usando **fetch**, **Axios**, uma **sessĂŁo persistente** e mais](/docs/examples/local-server). + +
+ +## Boas PrĂĄticas đŸ‘źđŸœ + +### ✅ Sinalize o status "ready" + +Quando possĂ­vel, defina uma saĂ­da do console para indicar que o serviço estĂĄ pronto.
+Isso irĂĄ permitir que vocĂȘ evite execuçÔes prematuras e vazamentos de porta. + +### ✅ Defina um tempo limite + +Definindo um tempo limite, vocĂȘ evita processos indefinidos que nĂŁo concluem nem com sucesso nem com falha. + +### ✅ Encerre seu serviço quando o trabalho estiver concluĂ­do + +VocĂȘ nĂŁo precisa necessariamente encerrar seu serviço em segundo plano como a Ășltima linha do teste, se ele nĂŁo estiver mais em uso. + +```ts +import { startService } from 'poku'; + +const server = await startService('server.js', { + /** + * Espere pelo "ready" na saĂ­da do console + */ + startAfter: 'ready', + + /** + * Por padrĂŁo, o `timeout` Ă© `60000` (1 minuto) tanto para sucesso quanto para falha + */ + timeout: 60000, +}); + +await server.end(); +``` + +:::tip + +VocĂȘ pode passar uma porta para `end` para forçar o tĂ©rmino do subprocesso em segundo plano para o **Bun** e o **Deno**. + +â„č Para usar a porta em `end`, vocĂȘ irĂĄ precisar do `lsof` para **Unix** ou `netstat` para **Windows**. + +::: + +:::info +Se vocĂȘ estiver enfrentando problemas ao usar esse recurso com o **Bun**, consulte [**oven-sh/bun#11055**](https://github.com/oven-sh/bun/issues/11055) ao usar o mĂ©todo `end` passando uma porta ou [**oven-sh/bun#7441**](https://github.com/oven-sh/bun/issues/7441) para subprocessos nĂŁo concluĂ­dos. +::: + + + +Liberação de uma porta que estĂĄ vazando: + +```bash +lsof -i :PORT +``` + +- Substitua `PORT` pelo nĂșmero da porta que vocĂȘ estĂĄ investigando. + +Em seguida, use o `PID` retornado com o comando `kill`: + +```bash +kill -9 PID +``` + +- Substitua `PID` pelo ID do processo atual que vocĂȘ encontrou usando o comando `lsof`. + + + +
+ +## OpçÔes DisponĂ­veis + +```ts +type StartServiceOptions = { + /** + * - Por padrĂŁo, serĂĄ resolvido na primeira saĂ­da do console + * - Definindo uma string: ele aguardarĂĄ uma string especĂ­fica na saĂ­da do console para resolver + * - Definindo um nĂșmero: ele aguardarĂĄ o tempo em milissegundos para resolver + * + * --- + * + * â„č `startAfter` Ă© sensĂ­vel a maiĂșsculas e minĂșsculas. + * + * --- + * + * @default undefined + */ + startAfter?: string | number; + /** + * Encerra o serviço sem sucesso nem falha apĂłs: + * @default 60000 + */ + timeout?: number; + /** + * Exibe a saĂ­da do serviço + */ + verbose?: boolean; + /** + * Especifica um caminho de destino para iniciar o processo + * + * @default "./" + */ + cwd?: string | undefined; + /** + * Por padrĂŁo, o Poku tentarĂĄ identificar a plataforma atual, mas vocĂȘ pode especificĂĄ-la manualmente + */ + platform?: 'node' | 'bun' | 'deno'; +}; + +type End = (port?: number | number[]) => Promise; +``` diff --git a/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/helpers/todo.mdx b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/helpers/todo.mdx new file mode 100644 index 00000000..8dc37c5c --- /dev/null +++ b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/helpers/todo.mdx @@ -0,0 +1,61 @@ +--- +sidebar_position: 10 +tags: [boilerplate] +--- + +# 📋 todo + +O `.todo` Ă© um auxiliar estendido para `describe`, `it` e `test` para ajudĂĄ-lo a planejar testes futuros. + +## Uso BĂĄsico + +### Mensagem simples + +```ts +import { describe, it, test } from 'poku'; + +describe.todo('todo: Teste Futuro'); + +it.todo('todo: Teste Futuro'); + +test.todo('todo: Teste Futuro'); +``` + +- NĂŁo hĂĄ diferença entre as funcionalidades. + +TambĂ©m em contextos internos: + +```ts +import { describe, it } from 'poku'; + +describe(() => { + it.todo('todo: Teste Futuro'); + + it('Teste real', () => { + /* ... */ + }); +}); +``` + +### Ignorando um callback + +Isso pode ser Ăștil quando vocĂȘ jĂĄ tem uma ideia ou protĂłtipo do que deseja testar, mas nĂŁo quer que o teste seja executado de fato.
+TambĂ©m pode ser Ăștil para testes que pararam de funcionar inesperadamente devido a algum evento externo, necessitando de maior atenção. + +```ts +import { describe, it } from 'poku'; + +describe.todo('todo: Teste Futuro', () => { + it(async () => { + process.exit(1); + }); +}); +``` + +- O mĂ©todo recebido por `todo` e tudo dentro dele serĂĄ completamente ignorado. + +
+ +:::note +Ao usar `beforeEach` ou `afterEach`, eles nĂŁo serĂŁo acionados por testes com `.todo`. +::: diff --git a/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/poku/include-files.mdx b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/poku/include-files.mdx new file mode 100644 index 00000000..e137dc23 --- /dev/null +++ b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/poku/include-files.mdx @@ -0,0 +1,139 @@ +--- +sidebar_position: 1 +--- + +import { History } from '@site/src/components/History'; +import { Stability } from '@site/src/components/Stability'; + +# 📩 Incluir DiretĂłrios e Arquivos + +Por padrĂŁo, o **Poku** busca por arquivos _`.test.`_ e `.spec.`, mas vocĂȘ pode customizĂĄ-lo usando a opção [`filter`](/docs/documentation/poku/options/filter). + +Suporte para mĂșltiplos caminhos em qualquer ordem., + <> + Flag --include depreciada. + , + <> + MantĂ©m suporte retroativo para mĂșltiplos caminhos separados por + vĂ­rgula para evitar mudanças incompatĂ­veis. + , + <> + + , + ], + }, + +]} +/> + +## CLI + +### Uso Comum + +```bash +# Equivalente Ă  ./ +npx poku +``` + +- Executa todos os testes sequencialmente. + +```bash +# Equivalente Ă  ./ +npx poku --parallel +``` + +- Executa todos os testes em paralelo. + +```bash +npx poku ./test +``` + +- Executa todos os testes do diretĂłrio `./test`. + +:::tip +VocĂȘ pode passar tanto diretĂłrios quanto arquivos. +::: + +:::note +NĂŁo Ă© possĂ­vel executar testes nos diretĂłrios `.git` e `node_modules`. +::: + +
+ +### Definindo mĂșltiplos caminhos + +```bash +npx poku caminhoDoTesteA caminhoDoTesteB +``` + +
+ +### Estendendo padrĂ”es Glob a partir do shell + +VocĂȘ tambĂ©m pode estender os **padrĂ”es do Glob** com `npx`, `bun`, `yarn`, etc. + +Por exemplo, executando todos os testes unitĂĄrios de um _monorepo_: + +```sh +npx poku ./packages/**/test/unit +``` + +Agora, listando todos os arquivos `.js` em vez do padrĂŁo `.test.|.spec.`: + +```sh +npx poku --filter='.js' ./packages/**/test/unit +``` + +Ou tambĂ©m, ao anular o `filter`: + +```sh +npx poku --filter='' ./packages/**/test/unit/*.js +``` + +
+ +### `--include` + + + +
+ +## API + +> `poku(caminhosDoTestes: string | string[])` + +```ts +await poku('caminhoDoTeste'); +``` + +```ts +await poku(['caminhoDoTesteA', 'caminhoDoTesteB']); +``` + +```ts +await poku('./'); +``` + +
+ +Em seguida, execute o arquivo diretamente com a plataforma de sua escolha, por exemplo: + +```bash +node test/run.test.js +``` + +```bash +npx tsx test/run.test.ts +``` + +
diff --git a/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/examples/local-server.mdx b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/examples/local-server.mdx new file mode 100644 index 00000000..e679f122 --- /dev/null +++ b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/examples/local-server.mdx @@ -0,0 +1,200 @@ +--- +sidebar_position: 1 +tags: [background, server, service, package.json, scripts, supertest] +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import { FAQ } from '@site/src/components/FAQ'; + +# Servidor Local + +Vamos criar um servidor simples: + + + + +```js +// highlight-start +import { createServer } from 'node:http'; + +createServer((_, res) => { + res.writeHead(200, { 'Content-Type': 'application/json' }); + res.end(JSON.stringify({ name: 'Poku' })); +}).listen(4000, () => console.log('ready')); + +// highlight-end +``` + + + + +```js +// highlight-start +Bun.serve({ + port: 4000, + fetch: () => + new Response(JSON.stringify({ name: 'Poku' }), { + headers: { 'Content-Type': 'application/json' }, + }), +}); + +console.log('ready'); +// highlight-end +``` + + + + +```ts +// highlight-start +Deno.serve({ + port: 4000, + handler: () => + new Response(JSON.stringify({ name: 'Poku' }), { + headers: { 'Content-Type': 'application/json' }, + }), + onListen: () => console.log('ready'), +}); +// highlight-end +``` + + + + +E agora, teste-o: + + + + +```js +import { assert, startService } from 'poku'; + +const server = await startService('server.js', { + // Aguarde pelo "ready" na saĂ­da do console + startAfter: 'ready', +}); + +// Use a biblioteca de requisiçÔes que preferir +// highlight-start +const res = await fetch('http://localhost:4000'); +const data = await res.json(); +// highlight-end + +assert.strictEqual(res.status, 200, 'O servidor estĂĄ ativo'); +assert.deepStrictEqual(data, { name: 'Poku' }, 'O Poku estĂĄ aqui'); + +server.end(); +``` + + + + + + +**Apenas faça isso** 🚀 + +Aqui estĂĄ um exemplo usando [**Axios**](https://github.com/axios/axios): + +```js +import { assert, startService } from 'poku'; +// highlight-start +import axios from 'axios'; +import axiosCookieJarSupport from 'axios-cookiejar-support'; +import { CookieJar } from 'tough-cookie'; + +// highlight-end +const server = await startService('server.js'); + +// highlight-start +axiosCookieJarSupport(axios); + +const cookieJar = new CookieJar(); + +export const api = axios.create({ + withCredentials: true, + jar: cookieJar, +}); + +const { data } = await api.get('http://localhost:4000'); +// highlight-end + +assert.deepStrictEqual(data, { name: 'Poku' }, 'O Poku estĂĄ aqui'); +``` + + + +:::tip + +- **Biblioteca de requisiçÔes:** VocĂȘ pode usar [**Axios**](https://github.com/axios/axios), [**Node Fetch**](https://github.com/node-fetch/node-fetch) ou qualquer outro que quiser 💙 +- **Servidor:** VocĂȘ pode usar qualquer servidor que quiser, como [**Express**](https://github.com/expressjs/express), [**Koa**](https://github.com/koajs/koa), etc. +- [**NextJS**](https://github.com/vercel/next.js), [**ViteJS**](https://github.com/vitejs/vite), [**nodemon**](https://github.com/remy/nodemon) e mais? Veja abaixo đŸ‘‡đŸ» + +::: + +
+ +VocĂȘ tambĂ©m pode iniciar seu servidor usando o `startScript`. + + + + +```js +import { assert, startScript } from 'poku'; + +const server = await startScript('start', { + // Aguarde pelo "ready" na saĂ­da do console + startAfter: 'ready', +}); + +// Use a biblioteca de requisiçÔes que vocĂȘ preferir. +// highlight-start +const res = await fetch('http://localhost:4000'); +const data = await res.json(); +// highlight-end + +assert.strictEqual(res.status, 200, 'O servidor estĂĄ ativo'); +assert.deepStrictEqual(data, { name: 'Poku' }, 'O Poku estĂĄ aqui'); + +server.end(); +``` + + + + +```json +{ + "script": { + "start": "node server.js" + } +} +``` + + + + +```json +{ + "script": { + "start": "bun server.js" + } +} +``` + + + + +```json +{ + "tasks": { + "start": "deno run --allow-net server.js" + } +} +``` + + + + +:::tip +Usando o `startScript`, vocĂȘ pode executar [**NextJS**](https://github.com/vercel/next.js), [**SvelteJS**](https://github.com/sveltejs/svelte), [**nodemon**](https://github.com/remy/nodemon) e todos os scripts que vocĂȘ sempre usou đŸ· +::: diff --git a/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/examples/parameterized-tests.mdx b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/examples/parameterized-tests.mdx new file mode 100644 index 00000000..56ab6de8 --- /dev/null +++ b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/examples/parameterized-tests.mdx @@ -0,0 +1,82 @@ +--- +tags: [examples, promise, tutorial, parameterized, parametrized] +sidebar_position: 0.5 +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import MidLevel from '@site/static/img/mid-level.svg'; + +# Testes parametrizados + +Testes parametrizados permite que vocĂȘ execute a mesma lĂłgica de teste com diferentes entradas e resultados esperados. Isso ajuda a testar em vĂĄrios cenĂĄrios sem escrever testes repetitivos. + +Por exemplo: + +```ts +import { assert, test } from 'poku'; + +const casosDeTeste = [ + { + esperado: true, + entrada: { name: 'Alice', role: 'admin' }, + casoDeTeste: 'Ă© admin', + }, + { + esperado: false, + entrada: { name: 'Bob', role: 'user' }, + casoDeTeste: 'nĂŁo Ă© admin', + }, +]; + +const isAdmin = (user) => user.role === 'admin'; + +for (const { esperado, entrada, casoDeTeste } of casosDeTeste) { + test(casoDeTeste, () => { + const atual = isAdmin(entrada); + + assert.strictEqual(atual, esperado); + }); +} +``` + +## Usando promesas + +Lidando com operaçÔes assĂ­ncronas sequencialmente dentro de testes parametrizados usando promesas: + +```ts +import { assert, test } from 'poku'; + +const casosDeTeste = [ + { + esperado: true, + entrada: { name: 'Alice', role: 'admin' }, + casoDeTeste: 'Ă© admin', + }, + { + esperado: false, + entrada: { name: 'Bob', role: 'user' }, + casoDeTeste: 'nĂŁo Ă© admin', + }, +]; + +const isAdmin = (user) => Promise.resolve(user.role === 'admin'); + +for (const { esperado, entrada, casoDeTeste } of casosDeTeste) { + await test(casoDeTeste, async () => { + const atual = await isAdmin(entrada); + + assert.strictEqual(atual, esperado); + }); +} +``` + +:::tip +Para executar operaçÔes assĂ­ncronas em paralelo, simplesmente remova `await` de `test` ou `it`. +::: + +
+ +:::info +Esses exemplos foram baseados [nesse comentårio](https://github.com/wellwelwel/poku/issues/566#issuecomment-2241496155). +::: diff --git a/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/examples/promises.mdx b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/examples/promises.mdx new file mode 100644 index 00000000..40c10fd0 --- /dev/null +++ b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/examples/promises.mdx @@ -0,0 +1,144 @@ +--- +tags: [examples, promise, beforeAll, afterAll, tutorial, roadmap] +sidebar_position: 0 +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import MidLevel from '@site/static/img/mid-level.svg'; + +# Promesas + +O uso da [sintaxe nativa **JavaScript** nos testes](/docs/philosophy#javascript-essence-for-tests-) é uma das principais diferenças entre o **Poku** e outros executores de testes, o que possibilita seu uso em vårias plataformas. + +:::tip +Não é necessårio usar `await` para testes que não são assíncronos. +::: + +Aqui estão alguns exemplos de testes sequenciais e concorrentes no mesmo arquivo, além de como realizar uma ação após todos os testes terem sido concluídos: + +### Executando testes assíncronos no mesmo arquivo em paralelo + +```js +import { test, assert, sleep } from 'poku'; + +test(async () => { + const atual = 1; + const esperado = 1; + + await sleep(2000); + + assert.strictEqual(atual, esperado); +}); + +test(async () => { + const atual = 2; + const esperado = 2; + + await sleep(1000); + + assert.strictEqual(atual, esperado); +}); +``` + +
+ +### Executando testes assĂ­ncronos no mesmo arquivo sequencialmente (aguardando nĂ­vel superior) + +```js +import { test, assert, sleep } from 'poku'; + +await test(async () => { + const atual = 1; + const esperado = 1; + + await sleep(2000); + + assert.strictEqual(atual, esperado); +}); + +await test(async () => { + const atual = 2; + const esperado = 2; + + await sleep(1000); + + assert.strictEqual(atual, esperado); +}); +``` + +
+ +### Executando testes assĂ­ncronos no mesmo arquivo sequencialmente + +```js +import { describe, it, assert, sleep } from 'poku'; + +describe(async () => { + await it(async () => { + const atual = 1; + const esperado = 1; + + await sleep(2000); + + assert.strictEqual(atual, esperado); + }); + + await it(async () => { + const atual = 2; + const esperado = 2; + + await sleep(1000); + + assert.strictEqual(atual, esperado); + }); +}); +``` + +
+ +## Aguarando todos os testes serem executados para realizar uma ação posterior + +```js +import { describe, it, assert, sleep } from 'poku'; + +describe(async () => { + console.log('Imprimindo isso antes de todos os testes đŸƒđŸ»â€â™€ïž'); + + await Promise.all([ + test(async () => { + const atual = 1; + const esperado = 1; + + await sleep(2000); + + assert.strictEqual(atual, esperado); + }), + + test(async () => { + const atual = 2; + const esperado = 2; + + await sleep(1000); + + assert.strictEqual(atual, esperado); + }), + ]); + + console.log('Imprimindo isso depois de todos os testes 😮'); +}); +``` + +:::tip +Para mĂșltiplos `describe` ou `test` assĂ­ncronos, vocĂȘ tambĂ©m pode usar `await` para executĂĄ-los sequencialmente. +::: + +
+ +:::danger Be careful +Ao usar `beforeEach` and `afterEach` assĂ­ncronos, Ă© necessĂĄrio usar `await` mesmo que os auxiliares `test` ou `it` nĂŁo tenham eventos assĂ­ncronos. +::: + +:::note +Se vocĂȘ encontrar algum erro de digitação, sinta-se Ă  vontande para abrir um **Pull Request** corrigindo-o. +:::