diff --git a/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/assert/index.mdx b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/assert/index.mdx new file mode 100644 index 00000000..2b0567dc --- /dev/null +++ b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/assert/index.mdx @@ -0,0 +1,189 @@ +--- +sidebar_position: 2 +tags: [assert, assertions, expect] +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import { FAQ } from '@site/src/components/FAQ'; + +# 🕵🏻 Assert + +O **Poku** inclui o método `assert` nativo do [**Node.js**][node-version-url], mantendo tudo como está, mas fornecendo legibilidade para humanos.
+Suporta tanto o [**Bun**][bun-version-url] quanto o [**Deno**][deno-version-url]. + +[node-version-url]: https://github.com/nodejs/node +[bun-version-url]: https://github.com/oven-sh/bun +[deno-version-url]: https://github.com/denoland/deno + +- Compatível com [**Node.js**][node-version-url], [**Bun**][bun-version-url] e [**Deno**][deno-version-url] + +> O `assert` é usado para escrever testes e verificar se seu código funciona como esperado, comparando valores e lançando erros 🧑🏻‍🎓 + +## Migrando para o `assert` do **Poku** + +_Mas apenas se você quiser, é claro._ + +Asserções padrões: + +```diff +- import assert from 'node:assert'; ++ import { assert } from 'poku'; +``` + +Asserções estritas: + +```diff +- import assert from 'node:assert/strict'; ++ import { strict as assert } from 'poku'; +``` + +- O método `strict` está disponível para **Node.js 16** em diante, **Bun** e **Deno**. + +```ts +assert(true, 'Isso é válido 🧪'); +assert.strictEqual(1, '1', 'O Poku irá descrever isso e mostrar um erro 🐷'); +// ... +``` + +:::tip +O `assert` do **Poku** usará a mensagem exatamente como seria ao usar `describe` e `it`.
+Seu **Poku** está esperando por você 🐷✨ +::: + +
+ +📘 Para aprender sobre asserções, veja o tutorial rápido: [De um teste de asserção básico à sua execução](/docs/tutorials/beginner). + +
+ +## Métodos Disponíveis + +```ts +import { assert } from 'poku'; +// import { strict as assert } from 'poku'; +``` + + + +### Verdadeira + +```ts +assert(valor[, mensagem]) +``` + +```ts +assert.ok(valor[, mensagem]) +``` + +### Igualdade + +```ts +assert.equal(atual, esperado[, mensagem]) +``` + +```ts +assert.strictEqual(atual, esperado[, mensagem]) +``` + +### Igualdade Profunda + +```ts +assert.deepEqual(atual, esperado[, mensagem]) +``` + +```ts +assert.deepStrictEqual(atual, esperado[, mensagem]) +``` + +### Correspondente + +```ts +assert.match(string, regexp[, mensagem]) +``` + +### Sucesso + +```ts +assert.doesNotReject(asyncFn[, erro][, mensagem]) +``` + +```ts +assert.doesNotThrow(fn[, erro][, mensagem]) +``` + + + + + +### Desigualdade + +```ts +assert.notEqual(atual, esperado[, mensagem]) +``` + +```ts +assert.notStrictEqual(atual, esperado[, mensagem]) +``` + +### Desigualdade Profunda + +```ts +assert.notDeepEqual(atual, esperado[, mensagem]) +``` + +```ts +assert.notDeepStrictEqual(atual, esperado[, mensagem]) +``` + +### Não Correspondente + +```ts +assert.doesNotMatch(string, regexp[, mensagem]) +``` + +### Falha + +```ts +assert.rejects(asyncFn[, erro][, mensagem]) +``` + +```ts +assert.throws(fn[, erro][, mensagem]) +``` + + + + + +### Falso + +```ts +assert.ifError(valor); +``` + +- _Teste para um valor de erro, útil em callbacks_ + +### Falha Forçada + +```ts +assert.fail([mensagem]); +``` + + + +Você pode seguir a [**documentação do assert**](https://nodejs.org/api/assert.html) da documentação do **Node.js**. + +:::note +Para o **Node.js**, os métodos `assert.match` e `assert.doesNotMatch` estão disponíveis a partir da versão 12 ou superior. +::: + +:::info + +Para compilar testes usando `assert` 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/before-after-each/in-code.mdx b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/helpers/before-after-each/in-code.mdx new file mode 100644 index 00000000..b8affb07 --- /dev/null +++ b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/helpers/before-after-each/in-code.mdx @@ -0,0 +1,68 @@ +--- +sidebar_position: 2 +tags: [hooks, setup, teardown] +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# No Código + +## `beforeEach` e `afterEach` + +Tanto `beforeEach` quanto `afterEach` são recomendados para testes que utilizam um estado global específico para cada teste.
+Por exemplo, populando ou reiniciando um banco de dados antes e/ou depois de várias asserções. + +### Uso Básico + +```ts +import { test, beforeEach, afterEach } from 'poku'; + +const prepareService = () => true; +const resetService = () => true; + +beforeEach(() => prepareService()); + +afterEach(() => resetService()); + +test(() => { + // faça o que quiser +}); + +test(() => { + // faça o que quiser +}); +``` + +### Usando promessas + +```ts +import { test, beforeEach, afterEach } from 'poku'; + +const prepareService = () => new Promise((resolve) => resolve(true)); + +const resetService = () => new Promise((resolve) => resolve(true)); + +beforeEach(async () => await prepareService()); +afterEach(async () => await resetService()); + +await test(async () => { + // faça o que quiser +}); + +await test(async () => { + // faça o que quiser +}); +``` + +:::tip + +Você pode sobrescrever tanto `beforeEach` quanto `afterEach` declarando-os novamente a qualquer momento. + +O **Poku** fornece três métodos opcionais tanto para `beforeEach` quanto para `afterEach`: + +- `.pause()` +- `.continue()` +- `.reset()` + +::: diff --git a/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/helpers/before-after-each/per-file.mdx b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/helpers/before-after-each/per-file.mdx new file mode 100644 index 00000000..866f5415 --- /dev/null +++ b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/helpers/before-after-each/per-file.mdx @@ -0,0 +1,63 @@ +--- +sidebar_position: 1 +tags: [hooks, setup, teardown] +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import { FAQ } from '@site/src/components/FAQ'; +import Success from '@site/static/img/each-success.png'; +import Failure from '@site/static/img/each-fail.png'; + +# Por Arquivo + +## Executando um callback antes e depois de cada arquivo de teste + +- [x] `poku` **API** +- [ ] `poku` **CLI** + +O **Poku** traz uma maneira simples de executar um callback antes e/ou depois de cada arquivo de teste. + + + + + ```ts + import { poku } from 'poku'; + + const prepareService = () => new Promise((resolve) => resolve(undefined)); + const resetService = () => new Promise((_, reject) => reject('Vamos fazer com que falhe')); + + await poku('test/unit', { + beforeEach: prepareService, + afterEach: resetService, + }); + ``` + + ```bash + npx poku test/run.test.js + ``` + + + + + + + + + + + + + + + + +
+ +:::tip +O modo "por arquivo" se aproxima dos plugins, embora essa não fosse a intenção original. +::: + +:::danger +Embora também funcione com execuções `parallel`, é fortemente desaconselhado usar esses recursos para testes concorrentes. +::: diff --git a/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/helpers/containers.mdx b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/helpers/containers.mdx new file mode 100644 index 00000000..591262a9 --- /dev/null +++ b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/helpers/containers.mdx @@ -0,0 +1,267 @@ +--- +sidebar_position: 6 +tags: [containers] +--- + +import { FAQ } from '@site/src/components/FAQ'; + +# 🐳 Contêineres + +Uma API mínima para auxiliar testes que requerem contêineres ou testes que são executados dentro de contêineres. + +> Esse auxiliar pressupõe que você já tem uma compreensão básica de como o **Docker** funciona. + +## docker + +### compose + +Inicie contêineres a partir de um **docker-compose.yml** em segundo plano. + +```ts +import { docker } from 'poku'; + +const compose = docker.compose(); + +// Inicia o(s) contêiner(es) +await compose.up(); + +/** + * Testes vêm aqui 🧪 + */ + +// Interrompe o(s) contêiner(es) +await compose.down(); +``` + + + +```ts +export type DockerComposeConfigs = { + /** + * Especifica o caminho do **docker-compose.yml** + * + * --- + * + * @default "./docker-compose.yml" + */ + file?: string; + + /** + * Especifica o nome do projeto. + */ + projectName?: string; + + /** + * Especifica um caminho `.env` para o **docker-compose.yml**. + */ + envFile?: string; + + /** + * Define o diretório raiz onde o processo irá rodar. + * + * --- + * + * @default "." + */ + cwd?: string; + + /** + * Força a reconstrução das imagens (**Dockerfile**). + */ + build?: boolean; + + /** + * Inicia apenas um serviço específico do **docker-compose.yml**. + */ + serviceName?: string; + + /** + * Não executa o contêiner em segundo plano e retorna o resultado de saída do processo do contêiner (boolean). + * + * - Defina como `false` para testar se um contêiner foi executado e finalizado com sucesso. + * + * --- + * + * @default true + */ + detach?: boolean; + + /** + * Mostra logs do **Docker** em tempo real. + */ + verbose?: boolean; +}; +``` + + + +
+ +### dockerfile + +Constrói e inicia contêineres a partir de **Dockerfiles** em segundo plano. + +```ts +import { docker } from 'poku'; + +const dockerfile = docker.dockerfile({ + containerName: 'nome-do-contêiner', + tagName: 'nome-da-imagem', +}); + +// Constrói a imagem a partir do Dockerfile +await dockerfile.build(); + +// Inicia o contêiner +await dockerfile.start(); + +/** + * Testes vêm aqui 🧪 + */ + +// Interrompe e remove tanto o contêiner quanto a imagem +await dockerfile.remove(); +``` + +- Você também pode usar `.stop()` para interromper o contêiner de maneira suave sem removê-lo. + + + +```ts +export type DockerfileConfigs = { + /** + * Especifica o nome da imagem + * + * Por exemplo, `"nome"`, `"nome:tag"`. + */ + tagName: string; + + /** + * Especifica o nome do contêiner. + */ + containerName: string; + + /** + * Especifica o caminho do **Dockerfile** + * + * --- + * + * @default "./Dockerfile" + */ + file?: string; + + /** + * Especifica o caminho de contexto do **Dockerfile** + * + * - É diferente do `cwd`. + * + * --- + * + * @default "." + */ + context?: string; + + /** + * Especifica as portas a serem expostas. + * + * Por exemplo, `"6000:6000"`, `"8080:80"`, `"127.0.0.1:3306:3306"`. + */ + ports?: string[]; + + /** + * Especifica as variáveis de ambiente do contêiner. + * + * Por exemplo, `"VAR1"`, `"VAR1=value1"` + */ + environments?: string[]; + + /** + * Especifica um caminho para o arquivo `.env` no **Dockerfile**. + */ + envFile?: string; + + /** + * Força a construção da imagem sem cache. + */ + cache?: boolean; + + /** + * Não executa o contêiner em segundo plano e retorna o resultado de saída do processo do contêiner (boolean). + * + * - Defina como `false` para testar se um contêiner foi executado e finalizado com sucesso. + * + * --- + * + * @default true + */ + detach?: boolean; + + /** + * Define o diretório raiz onde o processo irá rodar. + * + * --- + * + * @default "." + */ + cwd?: string; + + /** + * Mostra logs do **Docker** em tempo real. + */ + verbose?: boolean; +}; +``` + + + +
+ +## Exemplos Reais + +Testes realizados dentro de um contêiner (**docker-compose.yml**) em um serviço específico com imagens personalizadas (**Dockerfile**), retornando a saída, interrompendo os contêineres e limpando as imagens: + +- [test/compatibility/bun-canary.test.ts](https://github.com/wellwelwel/poku/blob/main/test/compatibility/bun-canary.test.ts) + +
+ +Testes realizados dentro de um contêiner (**Dockerfile**), retornando a saída, interrompendo o contêiner e limpando a imagem: + +- [test/compatibility-by-dockerfile/bun-canary.test.ts](https://github.com/wellwelwel/poku/blob/main/test/compatibility-by-dockerfile/bun-canary.test.ts) + +
+ +Inicia um contêiner antes de toda a suíte de testes e o interrompe ao finalizar: + +> Exemplo de _API_ do **Poku**. + +```ts +import { poku, docker, exit } from 'poku'; + +const compose = docker.compose({ cwd: './test/docker' }); + +// Remove o contêiner se ele já existir antes de iniciar +await compose.down(); + +// Inicia o contêiner +await compose.up(); + +const result = await poku('./test/integration', { + noExit: true, +}); + +// Interrompe o contêiner +await compose.down(); + +// Mostra os resultados dos testes e finaliza o processo com o código de saída do teste. +exit(result); +``` + +```sh +node run.test.mjs +``` + +
+ +:::note +Esta não é uma _API_ completa e robusta projetada para criar um _ORM_ para **Docker**, mas uma **API** mínima focada em necessidades comuns de **integração** e **teste de ponta a ponta**. +::: diff --git a/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/helpers/describe.mdx b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/helpers/describe.mdx new file mode 100644 index 00000000..5bb26b13 --- /dev/null +++ b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/helpers/describe.mdx @@ -0,0 +1,102 @@ +--- +sidebar_position: 2 +tags: [boilerplate, tdd, bdd] +--- + +import { FAQ } from '@site/src/components/FAQ'; + +# 🧪 describe + +> `describe(título: string, opções?: DescribeOptions)` | `describe(mensagem: string, cb: () => void)` | `describe(cb: () => void)` + +## Usando como títulos de teste + +No **Poku**, o `describe` pode ser usado apenas como um `console.log` elegante para dar título aos seus conjuntos de testes no terminal. + +```ts +import { describe, assert } from 'poku'; + +describe('Título Teste'); + +assert(true, '1'); +assert(true, '2'); +``` + +### Personalização + +#### background + +Altere a cor de fundo para seu título pessoal. + +```ts +import { describe, assert } from 'poku'; + +describe('Título Teste', { background: 'blue' }); + +assert.ok(true, '1'); +assert.ok(true, '2'); +``` + + + +- `white` +- `black` +- `grey` +- `red` +- `green` +- `yellow` +- `blue` +- `magenta` +- `cyan` +- `brightRed` +- `brightGreen` +- `brightYellow` +- `brightBlue` +- `brightMagenta` +- `brightCyan` + + + +#### icon (prefixo) + +o **Poku** também permite a personalização do prefixo. + +> O ícone padrão é `☰`. + +```ts +import { describe, assert } from 'poku'; + +describe('Título Teste', { icon: '🔬' }); + +assert.ok(true, '1'); +assert.ok(true, '2'); +``` + +## Agrupamento de testes (usual) + +```ts +import { describe, assert } from 'poku'; + +describe(() => { + assert.equal(1 + 1, 2, '1 + 1 deve ser 2'); + assert.equal(2 + 2, 4, '2 + 2 deve ser 4'); +}); +``` + +```ts +import { describe, assert } from 'poku'; + +describe('Testes de soma', () => { + assert.equal(1 + 1, 2); + assert.equal(2 + 2, 4); +}); +``` + +```ts +import { describe, assert } from 'poku'; + +describe('Testes de soma', () => { + assert.equal(1 + 1, 2, '1 + 1 deve ser 2'); + assert.equal(2 + 2, 4, '2 + 2 deve ser 4'); +}); +``` diff --git a/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/helpers/env.mdx b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/helpers/env.mdx new file mode 100644 index 00000000..96d414d0 --- /dev/null +++ b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/helpers/env.mdx @@ -0,0 +1,86 @@ +--- +sidebar_position: 4 +tags: [env, .env, dotenv] +--- + +# ⚙️ env + +Lê um arquivo de ambiente e define as variáveis de ambiente. + +## CLI + +Carregando o `.env` por padrão: + +```sh +npx poku --env-file +``` + +Carregando um `.env` customizado: + +```sh +npx poku --env-file='caminho/para/meu/.env' +``` + +
+ +## API + +> Você pode definir um arquivo `.env` diretamente em um teste especifico ou usá-lo globalmente. + +Carregando o `.env` por padrão: + +```ts +import { envFile } from 'poku'; + +await envFile(); +``` + +Carregando um `.env` customizado: + +```ts +import { envFile, poku } from 'poku'; + +await envFile('caminho/para/meu/.env'); + +await poku('./'); +``` + +
+ +:::note +Não é possível recuperar arquivos de diretórios acima do processo atual, por exemplo, `../.env`. +::: + +
+ +:::danger +O **Poku** é feito inteiramente para fins de teste, por favor, não use essa funcionalidade fora dos testes. +::: + +
+ +## Exemplos Reais + +- `.env.test` + +```sh +HOST='localhost' +PORT='8080' +``` + +Então, em um arquivo de teste, você pode usá-lo como: + +```js +import { assert } from 'poku'; + +const host = process.env.HOST; +const port = process.env.PORT; + +// Seus testes vêm aqui +``` + +Em seguida, execute seus testes + +```sh +npx poku --env-file='.env.test' +``` diff --git a/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/helpers/it.mdx b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/helpers/it.mdx new file mode 100644 index 00000000..a2b452a9 --- /dev/null +++ b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/helpers/it.mdx @@ -0,0 +1,90 @@ +--- +sidebar_position: 3 +tags: [boilerplate, tdd, bdd] +--- + +# 🧪 it + +> `it(mensagem: string, cb: () => void)` | `it(cb: () => void)` + +O `it` é um auxiliar para ajudá-lo em casos como: + +- Usar o [`beforeEach` e `afterEach`](/docs/documentation/helpers/before-after-each/in-code) para cada `it` realizado + +## Uso Básico + +### Agrupando testes + +```ts +import { describe, it, assert } from 'poku'; + +describe('Conjunto de cálculos', () => { + it('Somas', () => { + assert.equal(1 + 1, 2); + assert.equal(2 + 2, 4); + }); + + it('Divisão', () => { + assert.equal(1 / 1, 1); + assert.equal(2 / 2, 1); + }); +}); +``` + +### Aguardando Promessas + +```ts +import { describe, it } from 'poku'; + +await describe(async () => { + await it(async () => { + // faça o que quiser + }); + + await it(async () => { + // faça o que quiser + }); +}); +``` + +### Executando em paralelo + +```ts +import { describe, it } from 'poku'; + +describe(() => { + it(async () => { + // faça o que quiser + }); + + it(async () => { + // faça o que quiser + }); +}); +``` + +### Aguardando múltiplas promessas + +```ts +import { describe, it } from 'poku'; + +await describe(async () => { + // faça algo antes + + await Promise.all([ + it(async () => { + // faça o que quiser + }), + + it(async () => { + // faça o que quiser + }), + ]); + + // faça algo depois +}); +``` + +:::tip +Você pode pensar nisso como `beforeAll` e `afterAll`. +::: 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 new file mode 100644 index 00000000..f962f9a9 --- /dev/null +++ b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/helpers/skip.mdx @@ -0,0 +1,53 @@ +--- +sidebar_position: 4 +--- + +# ⏭️ skip + +Você pode pular testes quando necessário: + +```ts +import { skip } from 'poku'; + +skip(); +``` + +Você também pode passar uma mensagem opcional para o método `skip`: + +```ts +import { skip } from 'poku'; + +skip('Pulando por algum motivo'); +``` + +:::important +Isto pulará o arquivo inteiro e é recomendável usá-lo no início do arquivo de teste. +::: + +--- + +## Exemplos + +Imagine que um teste específico não funcione em um _SO_ específico: + +```ts +import { test, skip } from 'poku'; +// destaca-início +import { platform } from 'node:process'; + +const isWindows = platform === 'win32'; + +// destaca-fim +if (isWindows) skip('Pulando devido à incompatibilidade com o Windows'); + +// Executa testes normalmente em outros sistemas operacionais +// destaca-início +test(() => { + // ... +}); +// destaca-fim +``` + +:::note +Testes pulados são considerados testes bem-sucedidos. +::: 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 new file mode 100644 index 00000000..dc42cf1c --- /dev/null +++ b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/helpers/startScript.mdx @@ -0,0 +1,170 @@ +--- +sidebar_position: 7 +tags: [background, server, service, package.json, scripts] +--- + +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 Script + +Execute seus scripts do `package.json` em um processo em segundo plano e teste-os 🧑🏻‍🔬 + +> startScript(caminhoDoArquivo: string, opções?: startScriptOptions); + +O `startScript` executa um script diretamente do seu `package.json` ou `deno.json` e o mantém em execução em um processo em segundo plano até que você o libere. + +
+
+ + + Bastante útil para testar seu + [**NextJS**](https://github.com/vercel/next.js), + [**NuxtJS**](https://github.com/nuxt/nuxt), + [**nodemon**](https://github.com/remy/nodemon) e todos os apps do projeto + 🚀 + +
+
+ + 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 adicionar plugins externos para algo tão simples, 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 "pronto" + +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 { startScript } from 'poku'; + +const server = await startScript('start', { + /** + * 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 StartScriptOptions = { + /** + * - Por padrão, Isso 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; + /** + * Especifique um caminho de destino para iniciar o processo + * + * @default "./" + */ + cwd?: string | undefined; + /** + * Por padrão, o Poku usará o `npm`. Altere conforme desejar. + */ + runner?: 'npm' | 'bun' | 'deno' | 'yarn' | 'pnpm'; +}; + +type End = (port?: number | number[]) => Promise; +``` diff --git a/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/helpers/test.mdx b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/helpers/test.mdx new file mode 100644 index 00000000..99fc22e7 --- /dev/null +++ b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/helpers/test.mdx @@ -0,0 +1,115 @@ +--- +sidebar_position: 1 +tags: [boilerplate, tdd, bdd] +--- + +# 🧪 test + +> `test(mensagem: string, cb: () => void)` | `test(cb: () => void)` + +`test` é um auxiliar para o ajudar em casos como: + +- Usar [`beforeEach` e `afterEach`](/docs/documentation/helpers/before-after-each/in-code) para cada `test` realizado +- Isolar ou agrupar seus testes no mesmo arquivo +- Executar testes no mesmo arquivo em paralelo + +## Uso Básico + +### Isolando escopos + +```ts +import { test, assert } from 'poku'; + +test(() => { + const minhaVar = 'a'; + + assert.strictEqual(minhaVar, 'a', 'Meu primeiro auxiliar de teste'); +}); + +test(() => { + const minhaVar = 'b'; + + assert.strictEqual(minhaVar, 'b', 'Meu segundo auxiliar de teste'); +}); +``` + +### Agrupando testes + +```ts +import { test, assert } from 'poku'; + +test(() => { + assert.equal(1 + 1, 2, '1 + 1 deve ser 2'); + assert.equal(2 + 2, 4, '2 + 2 deve ser 4'); +}); +``` + +```ts +import { test, assert } from 'poku'; + +test('Testes de soma', () => { + assert.equal(1 + 1, 2); + assert.equal(2 + 2, 4); +}); +``` + +```ts +import { test, assert } from 'poku'; + +test('Testes de soma', () => { + assert.equal(1 + 1, 2, '1 + 1 deve ser 2'); + assert.equal(2 + 2, 4, '2 + 2 deve ser 4'); +}); +``` + +### Aguardando promessas + +```ts +import { test } from 'poku'; + +await test(async () => { + // faça o que quiser +}); + +await test(async () => { + // faça o que quiser +}); +``` + +### Executando em paralelo + +```ts +import { test } from 'poku'; + +test(async () => { + // faça o que quiser +}); + +test(async () => { + // faça o que quiser +}); +``` + +### Aguardando múltiplas promessas + +```ts +import { test } from 'poku'; + +// faça algo antes + +await Promise.all([ + test(async () => { + // faça o que quiser + }), + + test(async () => { + // faça o que quiser + }), +]); + +// faça algo depois +``` + +:::tip +Você pode pensar nessa abordagem como `beforeAll` e `afterAll`. +::: diff --git a/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/poku/config-files.mdx b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/poku/config-files.mdx index dec4c53c..712e0040 100644 --- a/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/poku/config-files.mdx +++ b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/poku/config-files.mdx @@ -104,7 +104,7 @@ module.exports = defineConfig({ } /> -Criei um arquivo `.pokurc.json` (ou `.pokurc.jsonc`) no diretório raiz do seu projeto, por exemplo: +Crie um arquivo `.pokurc.json` (ou `.pokurc.jsonc`) no diretório raiz do seu projeto, por exemplo: ```js { diff --git a/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/poku/options/concurrency.mdx b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/poku/options/concurrency.mdx new file mode 100644 index 00000000..04734193 --- /dev/null +++ b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/poku/options/concurrency.mdx @@ -0,0 +1,23 @@ +--- +sidebar_position: 8 +--- + +# `concurrency` + +Quando utilizada a opção `parallel`, utilize `concurrency` para limitar o número de testes executando simultaneamente.
+O valor padrão é `0` (sem limite). + +## CLI + +```bash +npx poku --parallel --concurrency=4 ./test +``` + +## API + +```ts +await poku('./test', { + parallel: true, + concurrency: 4, +}); +``` diff --git a/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/poku/options/debug.mdx b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/poku/options/debug.mdx new file mode 100644 index 00000000..7cccf964 --- /dev/null +++ b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/poku/options/debug.mdx @@ -0,0 +1,38 @@ +--- +sidebar_position: 6 +--- + +import { History } from '@site/src/components/History'; + +# `debug` + +Por padrão, o **Poku** não exibe logs que não vêm do **`assert`** do **Poku**, mas você pode habilitá-los. + + + Suporte para a flag curta -d. + , + ], + }, + ]} +/> + +## CLI + +```bash +npx poku --debug ./test +``` + +- Flag curta: `-d`. + +## API + +```ts +await poku('./test', { + debug: true, +}); +``` diff --git a/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/poku/options/deno.mdx b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/poku/options/deno.mdx new file mode 100644 index 00000000..68e73286 --- /dev/null +++ b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/poku/options/deno.mdx @@ -0,0 +1,133 @@ +--- +sidebar_position: 98 +--- + +# `deno` + +Opções exclusivas para a plataforma **Deno**. + +## `allow` + +Altere as permissões para o **Deno**. + +Por padrão, o **Poku** utiliza `--allow-run`, `--allow-env`, `--allow-read`, `allow-hrtime` e `--allow-net`. + +### CLI + +```bash +npx poku --deno-allow='read, run' +``` + +```bash +npx poku --deno-allow='read=arquivo.js, run' +``` + +Limpe todas as permissões: + +```bash +npx poku --deno-allow='' +``` + +### API + +```ts +poku('./test', { + deno: { + allow: ['read', 'run' /* ... */], + }, +}); +``` + +```ts +poku('./test', { + deno: { + allow: ['read=arquivo.js', 'run' /* ... */], + }, +}); +``` + +Limpe todas as permissões: + +```ts +poku('./test', { + deno: { + allow: [], + }, +}); +``` + +
+ +## `deny` + +Altere as permissões para o **Deno**. + +### CLI + +```bash +npx poku --deno-deny='write, sys' +``` + +```bash +npx poku --deno-deny='env=HOME, write' +``` + +### API + +```ts +poku('./test', { + deno: { + deny: ['write', 'sys' /* ... */], + }, +}); +``` + +```ts +poku('./test', { + deno: { + deny: ['env=HOME', 'write' /* ... */], + }, +}); +``` + +
+ +## `cjs` + +> `poku(targetPaths: string | string[], configs?: Configs)` +> +> `cjs: boolean | string[]` + +Agora é possível executar testes que utilizam `require`, `module.exports` e `module` diretamente com o **Deno** 🎉 + +É uma ótima funcionalidade para testar se um projeto criado, principalmente em **Node.js** ou **Bun**, também é compatível com o **Deno** sem a necessidade de transpilar o código ou usar gambiarras. + +Para executar o **CommonJS** com o **Deno**, você pode usar: + +### CLI + +```bash +npx poku --deno-cjs +``` + +```bash +npx poku --deno-cjs='.js,.cjs' +``` + +### API + +```ts +await poku('./test', { + deno: { + cjs: true, + }, +}); +``` + +```ts +await poku('./test', { + deno: { + cjs: ['.js', '.cjs' /* ... */], + }, +}); +``` diff --git a/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/poku/options/fail-fast.mdx b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/poku/options/fail-fast.mdx new file mode 100644 index 00000000..38806747 --- /dev/null +++ b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/poku/options/fail-fast.mdx @@ -0,0 +1,22 @@ +--- +sidebar_position: 7 +tags: [bail] +--- + +# `failFast` + +Utilizando o `failFast`, o **Poku** irá parar a execução dos testes na primeira falha. + +## CLI + +```bash +npx poku --fail-fast ./test +``` + +## API + +```ts +await poku('./test', { + failFast: true, +}); +``` diff --git a/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/poku/options/no-exit.mdx b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/poku/options/no-exit.mdx new file mode 100644 index 00000000..b346b928 --- /dev/null +++ b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/poku/options/no-exit.mdx @@ -0,0 +1,49 @@ +--- +sidebar_position: 99 +--- + +# `noExit` + +Definindo `noExit` como `true`, o **Poku** não irá encerrar o processo e irá retornar o código de saída (`0` ou `1`).
+Você pode combinar essa opção com o método `exit` do **Poku** ou apenas usar o resultado, por exemplo: `process.exit(code)`. + +## API + +```ts +import { poku, exit } from 'poku'; + +const unit = await poku('test/unit', { + noExit: true, + parallel: true, + quiet: true, +}); + +// Faça algo + +const integration = await poku('test/integration', { + noExit: true, + quiet: true, +}); + +// Faça algo mais + +const code = unit === 0 && integration === 0 ? 0 : 1; + +// Faça algo mais novamente + +exit(code); +``` + +
+ +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/documentation/poku/options/quiet.mdx b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/poku/options/quiet.mdx new file mode 100644 index 00000000..3aaba655 --- /dev/null +++ b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/poku/options/quiet.mdx @@ -0,0 +1,45 @@ +--- +sidebar_position: 5 +--- + +import { History } from '@site/src/components/History'; + +# `quiet` + +Realize testes sem logs.
+Essa opção sobrescreve todas as configurações de `log`, saindo com um código e sem logs (veja abaixo). + + + Suporte para a flag curta -q. + , + ], + }, + ]} +/> + +## CLI + +```bash +npx poku --quiet ./test +``` + +- Flag curta: `-q`. + +## API + +```ts +await poku('./test', { + quiet: true, +}); +``` + +
+ +:::note +Como o **Poku** não transforma arquivos, testes utilizando `beforeEach` ou `afterEach` com consoles externos podem ser gerados. +::: diff --git a/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/poku/options/watch.mdx b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/poku/options/watch.mdx new file mode 100644 index 00000000..98cc82e4 --- /dev/null +++ b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/documentation/poku/options/watch.mdx @@ -0,0 +1,71 @@ +--- +sidebar_position: 9 +--- + +import { History } from '@site/src/components/History'; + +# `watch` + +Observa os eventos nos testes e arquivos que contêm testes (após executar todos os testes), reexecutando os arquivos de teste que são atualizados para cada novo evento. + + + Suporte para a flag curta -w. + , + ], + }, + ]} +/> + +## CLI + +```bash +npx poku --watch +``` + +Você pode utilizar a flag `--watch-interval` para definir um intervalo para os eventos de `watch` em milissegundos: + +> O padrão é `1500` + +```bash +npx poku --watch --watch-interval=1500 +``` + +- Flag curta: `-w`. + +
+ +:::tip + +Rapidamente redefina e reexecute todos os testes digitando rs no console, seguido de Enter. + +- Isso irá limpar e repopular todos os diretórios e arquivos a serem observados. +- Não é possível utilizá-lo enquanto os testes estão em execução. + +::: + +
+ +:::info + +Se não for possível determinar qual arquivo de teste depende do arquivo de origem alterado, nenhum teste será executado. + +::: + +
+ +:::note + +❌ Caminhos dinâmicos não são suportados: + +```ts +const dynamicPath = './algum-arquivo.js'; + +await import(dynamicPath); +``` + +:::