DEV Community: jacksonPrimo

Como fazer testes de integração com Node.js, Fastify, Vitest e Prisma 2026

jacksonPrimo — Sun, 12 Apr 2026 17:01:29 +0000

Após passar um bom periodo usando apenas Jest, recentemente resolvi dar uma chance para o Vitest e achei a ferramenta simplesmente sensacional, super simples e intuitiva para configurar.

Comecei a estudar utilizando ferramentas de IA para construção de alguns casos de teste mas não gostei muito do resultado, devido a configuração ser muito simples e haver muitos elementos mockados para testes que deveriam ser de integração e não unitários.

Resolvi então fazer minha estrutura seguindo algumas convenções e práticas que aprendi no mundo do Ruby On Rails como uso de Factories para criação de registros reais no banco, subir todas dependências via container antes de executar os casos de teste como PostgreSql e Redis. Com isto eu pude testar não somente os fluxos diferentes que o código seguia baseado nos parâmetros enviados como também se eles estavam sendo persistidos corretamente no banco.

Agora que estão contextualizados vamos começar.

Base do projeto

Primeiro vamos construir a base do projeto, começando pela configuração do typescript, fastify e zod.

$ npm init -y
$ npm install fastify zod fastify-type-provider-zod
$ npm install -D typescript tsx @types/node
$ npx tsc init

crie o arquivo de servidor:

// /src/server.ts
import fastify from "fastify";
import {
    hasZodFastifySchemaValidationErrors,
    serializerCompiler,
    validatorCompiler,
    type ZodTypeProvider,
} from "fastify-type-provider-zod";
import { env } from "./env";

const app = fastify().withTypeProvider<ZodTypeProvider>();

app.setValidatorCompiler(validatorCompiler);
app.setSerializerCompiler(serializerCompiler);

app.get("/", async (request) => {
    return "server is working"
});

export { app };

if (process.env.NODE_ENV !== 'test') {
    app
        .listen({ port: env.PORT, host: '0.0.0.0' })
        .then(() => {
            console.log(`server running on port ${env.PORT}`);
        });
}

Alguns pontos importantes aqui, usei algumas configurações adicionais como withTypeProvider, setValidatorCompiler e setSerializerCompiler para que o fastify saiba como interagir corretamente com o zod em suas validações a nível de controller, adicionei o link da documentação na descrição caso queiram se aprofundar no assunto. Outra questão é o start do servidor só ocorrer se o ambiente não for de teste, isso por que vamos reútilizar o "app" no nosso contexto de testes e não queremos rodar o servidor nesse contexto.

Adicione um arquivo para reúnir e tipar corretamente suas envs com o zod:

// /src/env.ts

import z from "zod";
const envSchema = z.object({
    DATABASE_URL: z.url(),
    JWT_SECRET: z.string(),
    PORT: z.coerce.number().default(3001),
});

export const env = envSchema.parse(process.env);

Configurando prisma

Agora vamos fazer a configuração do prisma com PostgreSQL, apenas para armazenarmos nossa tabela de usuários.

npm install prisma @types/pg --save-dev
npm install @prisma/client @prisma/adapter-pg pg dotenv

npx prisma

Será gerado um arquivo de configuração do prisma e a pasta de configuração do schema na raiz do projeto:

// prisma.config.ts
import "dotenv/config";
import { defineConfig, env } from "prisma/config";

export default defineConfig({
  schema: "prisma/schema.prisma",
  migrations: {
    path: "prisma/migrations",
  },
  datasource: {
    url: env("DATABASE_URL"),
  },
});

// prisma/schema.prisma
generator client {
  provider = "prisma-client"
  output   = "../generated/prisma"
}
datasource db {
  provider = "postgresql"
}

Adicione um arquivo de comunicação para o prisma

// src/lib/prisma.ts
import "dotenv/config";
import { PrismaPg } from "@prisma/adapter-pg";
import { PrismaClient } from "../generated/prisma/client";
import { env } from "../env";

const connectionString = `${env.DATABASE_URL}`;

const adapter = new PrismaPg({ connectionString });
const prisma = new PrismaClient({ adapter });

export { prisma };

Essa parte do setup do prisma é sempre bom seguir a documentação oficial pois de tempos em tempos algumas configurações mudam.

Agora vamos modificar nosso schema e em seguida rodar a migration para criarmos nossa tabela de usuário:

// prisma/schema.prisma
generator client {
  provider = "prisma-client"
  output   = "../src/generated/prisma"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

model User { 
  id                String      @id @default(uuid()) 
  email             String      @unique
  name              String
  passwordHash      String
  createdAt         DateTime    @default(now())
  updatedAt         DateTime    @updatedAt
}

Agora vamos gerar uma migration:

$ npx prisma migrate dev --name createUser

Aqui é importante que seu banco esteja disponível, então você pode subir um container com o PostgreSql para testes:

$ docker run --name pg-test-db -e POSTGRES_PASSWORD=mypassword -e POSTGRES_USER=myuser -p 5432:5432 -d postgres

Criando serviço de autenticação

Agora iremos criar um serviço simples de registro de usuário e login com jwt:

$ npm install jsonwebtoken bcryptjs

// src/helpers/authHelper.ts
import bcrypt from "bcryptjs";
import jwt from "jsonwebtoken";
import { env } from "../env";

export async function generatePasswordHash(password: string) {
  return await bcrypt.hash(password, 10);
}

export function generateAuthToken(userId: string) {
  return jwt.sign({ userId }, env.JWT_SECRET, { expiresIn: "7d" });
}

export function verifyAuthToken(token: string) {
  try {
    return jwt.verify(token, env.JWT_SECRET);
  } catch(_) {}
}

export async function comparePasswordHash(password: string, hash: string) {
  return await bcrypt.compare(password, hash);
}

// src/services/auth/registerUserService.ts
import { RegisterUserDto } from "../../dtos/RegisterUserDto";
import { CustomError } from "../../errors/customError";
import { generateAuthToken, generatePasswordHash } from "../../helpers/authHelper";
import { prisma } from "../../lib/prisma";

export async function registerUser(params: RegisterUserDto) {
  await verifyIfEmailAlreadyInUse(params.email)
  const passwordHash = await generatePasswordHash(params.password);
  const user = await prisma.user.create({
    data: {
      name: params.name,
      email: params.email,
      passwordHash: passwordHash
    },
  });
  return { accessToken: generateAuthToken(user.id) }
}

async function verifyIfEmailAlreadyInUse(email: string) {
  const userFound = await prisma.user.findFirst({ where: { email } });
  if (userFound) throw new CustomError("Este e-mail já está em uso", 400)
}

// src/dtos/RegisterUserDto.ts
import z from "zod";

export const RegisterUserValidation = z.object({
  name: z.string().nonempty(),
  email: z.email().nonempty(),
  password: z.string().nonempty().min(9)
})

export type RegisterUserDto = z.infer<typeof RegisterUserValidation>;

// src/services/auth/signinService.ts
import { SigninDto } from "../../dtos/SigninDto";
import { CustomError } from "../../errors/customError";
import { generateAuthToken, comparePasswordHash } from "../../helpers/authHelper";
import { prisma } from "../../lib/prisma";

export async function signin(params: SigninDto) {
  const notFoundMessage = "E-mail ou senha inválidos"
  const userFound = await prisma.user.findFirst({ where: { email: params.email } });
  if (!userFound) throw new CustomError(notFoundMessage, 404)

  const isPasswordValid = await comparePasswordHash(params.password, userFound.passwordHash)
  if (!isPasswordValid)
    throw new CustomError(notFoundMessage, 404)

  return {
    accessToken: generateAuthToken(userFound.id)
  }
}

// src/dtos/SigninDto.ts
import z from "zod";

export const SigninValidation = z.object({
  email: z.email().nonempty(),
  password: z.string().nonempty()
})

export type SigninDto = z.infer<typeof SigninValidation>;

// src/server.ts
import { RegisterUserValidation } from "./dtos/RegisterUserDto";
import { registerUser } from "./services/auth/registerUserService";
import { SigninValidation } from '../dtos/SigninDto';
import { signin } from '../services/auth/signinService';

app.post(
    '/auth/register', 
    { schema: { body: RegisterUserValidation } }, 
    async (request, reply) => {
        const response = await registerUser(request.body)
        reply.code(201).send(response)
    }
)

app.post(
    '/auth/login',
    { schema: { body: SigninValidation } },
    async (request, reply) => {
        const response = await signin(request.body)
        reply.code(201).send(response)
    }
)

Agora algo que sempre gosto de adicionar nas minhas APIs são middlewares para tratamento de erros e uma classe de erro customizada, vamos implementar isto:

// src/errors/customError.ts
export class CustomError extends Error {
  constructor(message: string, private code=500, private description="") {
    super(message)
  }

  public getCode() {
    return this.code
  }

  public getDescription() {
    return this.description
  }
}

// src/server.ts
app.setErrorHandler((error, request, reply) => {
    if (hasZodFastifySchemaValidationErrors(error)) {
        return reply.status(400).send({
            statusCode: 400,
            error: "invalid params",
            description: error.message
        });
    }
    else if (error instanceof CustomError) {
        return reply.status(error.getCode()).send({
            statusCode: error.getCode(),
            error: error.message,
            description: error.getDescription()
        });
    } else {
        return reply.status(500).send({
            statusCode: 500,
            error: "internal server error",
            description: error
        });
    }
});

"hasZodFastifySchemaValidationErrors(error)" é a forma de identificarmos e tratarmos erros de validação vindos do zod.
"error instanceof CustomError" seria para tratarmos erros comuns como e-mail já em uso, senha incorreta etc.
Caso não seja nenhum dos outros 2 casos, então consideramos como um erro de servidor, se fosse o caso de uma aplicação maior nesse escopo estariamos adicionando alguma ferramenta de monitoramento como o Sentry, ou adicionar um disparo de aviso via e-mail.

Setup para os testes

Enfim, agora que temos todo nosso projetinho construido, vamos implementar os testes, mas antes temos que fazer o setup para executar eles.

A ideia aqui é termos um container para cada dependência da aplicação como banco de dados, cache, filas etc. Podemos fazer isto de duas maneiras, uma seria adicionar tudo em um arquivo docker-compose.yml e subir antes de executar os testes, poderiamos rodar inclusive o proprio teste dentro de um container OU podemos usar uma ferramenta especializada em criar containers para testes chamada testcontainer.

O testcontainer existe para diferentes linguagens, meu primeiro contato com ela foi no Ruby On Rails por exemplo, ela oferece uma variedade bem grande de containers para serem trabalhados como MySql, PostgreSql, Redis, RabbitMq etc. No nosso caso como a única dependência é o postgres, vamos instalar apenas ela:

$ npm install @testcontainers/postgresql --save-dev

Nossa estrela da vez para a realização dos testes:

$ npm install -D vitest

Na raiz do projeto crie um arquivo de configuração para o vitest

// vitest.config.mts
import { defineConfig } from 'vitest/config'

export default defineConfig({
    test: {
        globalSetup: './tests/setup/global.ts',
        setupFiles: ['./tests/setup/reset-db.ts'],
        environment: 'node',
        globals: true,
        maxWorkers: 1
    },
})

Aqui tem 3 importantes campos de configuração:

globalSetup: irá rodar uma única vez antes de todos os testes, ele será responsável no nosso caso por subir os containers.
setupFiles: este executa antes de cada caso de teste, vai servir para resetarmos o banco. Isso garante que registros de um teste não entrem em conflito com os de outro, tornando eles isolados e independentes.
maxWorkers: seria para definirmos o nível de paralelismo da execução dos testes, no nosso caso como vamos resetar o banco a cada teste, é importante que não haja mais de 1 workers, do contrário um teste pode resetar o banco enquanto outro está executando. Agora vamos implementar os arquivos de configuração:

// tests/setup/global.ts
import { PostgreSqlContainer } from "@testcontainers/postgresql";
import { execSync } from 'node:child_process';

let container: any;

export async function setup() {
  console.log("Subindo o PostgreSQL Testcontainer...");
  const postgreContainer = await new PostgreSqlContainer("postgres:16-alpine")
    .withDatabase("dummy")
    .withUsername("dummy")
    .withPassword("dummy")
    .start();

  const uri = postgreContainer.getConnectionUri();

  console.log("Adicionando envs...")
  process.env.DATABASE_URL = uri;
  process.env.NODE_ENV = 'test';
  process.env.JWT_SECRET = 'secret';


  console.log("Rodando as migrations...")
  execSync('npx prisma migrate deploy', { stdio: 'inherit', env: { ...process.env, DATABASE_URL: uri } });
}

export async function teardown() {
  if (container) {
    console.log("Derrubando o Testcontainer...");
    await container.stop();
  }
}

Note que é aqui que:

subimos o container do nosso banco
setamos nossas envs
rodamos as migrations do banco

Antes de finalizar os testes precisamos derrubar estes containers, portanto a instancia do container fica em uma variável de escopo global no arquivo para ser encerrada na função teardown.

// tests/setup/reset-db.ts
import { beforeEach, afterAll } from 'vitest';
import { prisma } from '../../src/lib/prisma';

beforeEach(async () => {
    await prisma.$executeRawUnsafe(`TRUNCATE TABLE "Click", "Link", "User" CASCADE;`);
});

afterAll(async () => {
    await prisma.$disconnect();
});

Aqui estamos usando a operação truncate table para resetarmos os registros de forma mais segura.

Agora que temos o setup, podemos criar nossos testes:

// tests/integration/auth.spec.ts
import { describe, it, expect } from 'vitest';
import { prisma } from '../../src/lib/prisma';
import { app } from '../../src/server';
import { simpleUser } from '../factories/userFactory';

describe('User Registration Route', () => {
  it('should successfully register a new user', async () => {
    const response = await app.inject({
      method: 'POST',
      url: '/auth/register',
      payload: {
        name: 'Jackson Aquino',
        email: 'jackson@test.com',
        password: 'securepassword123'
      }
    });

    expect(response.statusCode).toBe(201);

    const body = JSON.parse(response.body);
    expect(body).toHaveProperty('accessToken');
    expect(typeof body.accessToken).toBe('string');

    const count = await prisma.user.count({ where: { name: 'Jackson Aquino', email: 'jackson@test.com'} });
    expect(count).toBe(1);
  });

  it('should return 400 when email is already in use', async () => {
    const userAlreadyRegistered = await simpleUser()

    const response = await app.inject({
      method: 'POST',
      url: '/auth/register',
      payload: {
        name: 'Jackson Aquino',
        email: userAlreadyRegistered.email,
        password: 'securepassword123'
      }
    });

    expect(response.statusCode).toBe(400);

    const body = JSON.parse(response.body);
    expect(body.error).toBe('Este e-mail já está em uso');
  });

  it('should return 400 when body validation fails (missing name)', async () => {
    const response = await app.inject({
      method: 'POST',
      url: '/auth/register',
      payload: {
        email: 'jackson@test.com',
        password: 'securepassword123'
      }
    });

    expect(response.statusCode).toBe(400);
    const body = JSON.parse(response.body);
    expect(body.error).toBe('invalid params');
    expect(body.description).toBe('body/name Invalid input: expected string, received undefined');
  });

  it('should return 400 when body validation fails (pasword length less than 9)', async () => {
    const response = await app.inject({
      method: 'POST',
      url: '/auth/register',
      payload: {
        name: 'jackson Aquino',
        email: 'jackson@test.com',
        password: '12345678'
      }
    });

    expect(response.statusCode).toBe(400);
    const body = JSON.parse(response.body);
    expect(body.error).toBe('invalid params');
    expect(body.description).toBe('body/password Too small: expected string to have >=9 characters');
  });
});

describe('User Login Route', () => {
  it('should successfully login when credentials are valid', async () => {
    const user = await simpleUser()
    const response = await app.inject({
      method: 'POST',
      url: '/auth/login',
      payload: {
        email: user.email,
        password: '123456789'
      }
    });

    expect(response.statusCode).toBe(201);
    const body = JSON.parse(response.body);
    expect(body).toHaveProperty('accessToken');
  });

  it('should return 404 when email does not exist', async () => {
    const response = await app.inject({
      method: 'POST',
      url: '/auth/login',
      payload: {
        email: 'unknown@test.com',
        password: 'securepassword123'
      }
    });

    expect(response.statusCode).toBe(404);
    const body = JSON.parse(response.body);
    expect(body.error).toBe('E-mail ou senha inválidos');
  });

  it('should return 404 when password is wrong', async () => {
    const user = await simpleUser()
    const response = await app.inject({
      method: 'POST',
      url: '/auth/login',
      payload: {
        email: user.email,
        password: 'wrongpassword'
      }
    });

    expect(response.statusCode).toBe(404);
    const body = JSON.parse(response.body);
    expect(body.error).toBe('E-mail ou senha inválidos');
  });
});

Note que existem funções chamadas "simpleUser" vindos de um diretório chamado factory, esse é um conceito que também aprendi do Ruby, nele temos o FactoryBot que cria registros no banco de forma que podemos reaproveitar esses registros em diferentes casos de teste. Então se houvessem testes de listagem de posts, comentários etc. Poderiamos usar o mesmo factory de criação de usuários.

// tests/factories/userFactory.ts
import { User } from "../../src/generated/prisma/client";
import { generatePasswordHash } from "../../src/helpers/authHelper";
import { generateShortCode } from "../../src/helpers/linkHelper";
import { prisma } from "../../src/lib/prisma";

export async function simpleUser(): Promise<User> {
  return await prisma.user.create({
    data: {
      name: "exemplo",
      email: "exemplo@gmail.com",
      passwordHash: await generatePasswordHash("123456789")
    },
  });
}

export async function randomUser(): Promise<User> {
  const randomCode = generateShortCode()
  return await prisma.user.create({
    data: {
      name: `exemplo-${randomCode}`,
      email: `exemplo-${randomCode}@gmail.com`,
      passwordHash: await generatePasswordHash("123456789")
    },
  });
}

Outra questão é que dessa forma não precisamos mockar operações que envolvem o banco, todas são chamadas e de fato fazem alterações no banco, o que conhecemos como efeitos colaterais. Ao final de cada teste podemos chamar o prisma e verificar se de fato os dados foram preenchidos corretamente, se obedecem as constraints do banco como e-mails únicos, regras de negócio como senhas terem obrigatoriamente no mínimo 9 digitos etc.

Referências:

Configurando AWS SQS no Ruby On Rails

jacksonPrimo — Fri, 03 Apr 2026 21:49:33 +0000

É importante ressaltar que dependendo da ação você quer executar haverá maneiras diferentes de configurar o SQS, por exemplo você pode querer usar ele apenas como producer, ou seja, apenas para enviar mensagens para uma fila que será processada por outra aplicação, usar como fila de processamento dos seus jobs ou configurar workers que irão escutar as mensagens da fila e processá-la por exemplo para disparar um e-mail ou processar arquivos.

Utilizando como producer

Essa é a configuração mais simples pois você só precisa configurar as envs e adicionar a gem do SDK.

Primeiro adicione a gem do SDK do aws para trabalhar com SQS:

# Gemfile
gem 'aws-sdk-sqs'

$ bundler install

Adicione as envs necessárias para o SDK, essas envs são esperadas pela gem para se comunicar com sua conta na aws:

AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=4
AWS_REGION=us-east-1
AWS_SQS_QUEUE_NAME=
AWS_QUEUE_URL=

Pode haver variações então sempre é bom dar uma conferida na documentação neste link

Agora basta instanciar o SDK e enviar a mensagem:

result = Aws::SQS::Client.new.send_message(
  queue_url: ENV['AWS_QUEUE_URL'],
  message_body: { order_id: "123" }.to_json
)

Utilizando como worker

Para isso utilizaremos a gem shoryuken que seria o equivalente ao Sidekiq para o Redis.

# Gemfile
gem 'shoryuken'

$ bundler install

Adicionamos um arquivo de configuração:

# config/shoryuken.yml
concurrency: 5
require: ./app/workers
queues:
  - [ <%= ENV.fetch('AWS_SQS_QUEUE_NAME') %>, 1]

O “require” força o Rails a carregar os workers dessa pasta em ambiente de development.

Caso o projeto não reconheça a pasta dos workers, basta adicionar essa configuração:

config.eager_load_paths.delete("#{Rails.root}/app/workers")
config.eager_load_paths.unshift("#{Rails.root}/app")

Dependendo da versão do rails pode variar, mas seria uma configuração de autoload para arquivos de pastas que não são padrão em projetos Rails como por exemplo “jobs”, “controllers”, “services” etc.

Agora basta criar seus workers para escutar as filas

class ExampleWorker
  include Shoryuken::Worker

  shoryuken_options queue: ENV.fetch('AWS_SQS_QUEUE_NAME'), auto_delete: true

  def perform(sqs_msg, body)
    payload = JSON.parse(body)
    ::ExampleService.new(payload).call
  end
end

Para ele ser reconhecido como worker, injetamos o módulo Shoryuken::Worker na classe.

Em shoryuken_options temos a opção queue que seria a fila que esse worker irá escutar e auto_delete que informa ao worker que deve apagar a mensagem do SQS após sua leitura ser feita com sucesso.

Para que os workers comecem a escutar as filas basta usar o comando:

$ bundle exec shoryuken -R -C config/shoryuken.yml

Onde a flag -R serve para carregar o ambiente do rails, carregando assim suas envs e gems.

E a flag -C seria para carregar o arquivo de configuração, sem ela teria que passar cada configuração nesse comando, como por exemplo as filas que devem ser escutadas.

Utilizando como fila de processamento de jobs

Aqui será utilizado novamente o shoryuken mas com uma configuração adicional, temos que mudar o queue_adapter do rails para utilizar essa gem.

# config/application.rb
config.active_job.queue_adapter = :shoryuken

Inicialmente o projeto gerencia o processamento do job tudo em memória, essa configuração serve para usar as configurações do shoryuken para gerenciar usando o SQS.

Agora basta criar um job

$ rails g job SayHello

class SayHelloJob < ActiveJob::Base
  queue_as ENV.fetch('AWS_SQS_QUEUE_NAME', :default)

  def perform(name)
    sleep(2)

    puts "Hello #{name}"
  end
end

Para testar o job utilize o console do rails e a função perform_later.

SayHelloJob.perform_later("jackson")

Um ponto interessante aqui é que se utilizar o perform_now, o job será executado mas não será enviado para o SQS, pois tudo será executado de forma sincrona em memória.

Dentro do SQS, você verá uma mensagem com o seguinte body:

{
    "job_class": "SayHelloJob",
    "job_id": "883d23f0-1997-xxxxx-xxxxxxxx",
    "provider_job_id": null,
    "queue_name": "queue-name-example",
    "priority":null,
    "arguments":[ "jackson" ],
    "executions": 0,
    "exception_executions": {},
    "locale": "en",
    "timezone": "UTC",
    "enqueued_at": "2026-04-03T12:57:41.629214813Z",
    "scheduled_at":null
}

Os argumentos passados no job ficarão dentro da chave “arguments” e os demais campos são configurações do próprio job.

Referências:
https://github.com/ruby-shoryuken/shoryuken/wiki/Getting-Started
https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/SQS/Client.html

Usando a opção 'hint' para adicionar frases de contexto no anki

jacksonPrimo — Sun, 19 Oct 2025 17:18:19 +0000

Eu estou usando a ferramenta anki para melhorar meu vocabulário do inglês, já tinha um certo tempo que eu procurava como fazer o seguinte passo a passo durante as revisões:
Mostrar apenas a palavra que quero lembrar → em seguida mostrar uma frase de contexto → e por fim mostrar o verso do card com a tradução e uma explicação sobre o significado.

Para que assim eu pudesse treinar primeiro tentar lembrar a palavra fora de contexto e caso eu não lembrasse mostrar então uma frase contextualizando e por fim a tradução com uma explicação.

Tentei usar o tipo ‘Cloze’ mas o texto oculto só era revelado junto ao verso do card, então pesquisando achei uma opção chamada ‘Hint’ que serve para esse proposito.
Para adicionar essa configuração basta seguir estes passos:

1 - Abra o Anki

2 - Ferramentas → Gerenciar tipos de notas

3 - Adicionar

4 - Selecione a opção Básico

5 - Dê um nome para o seu tipo de nota, no meu caso eu escolhi ‘Básico com frase de contexto’

6 - Agora selecione seu novo tipo criado e em seguida a opção ‘Campos’

Selecione frente e clique em adicionar, no meu caso eu dei o nome ‘Frase de contexto’ mas você pode escolher outro nome. Em seguida é só dar ok e salvar.

7 - Selecione novamente o tipo criado e agora vá na opção cartões

Inicialmente o modelo de frente vai ter apenas

{{Frente}}

Adicione as seguintes linhas:

<br>

{{hint:Frase de contexto}}

Ficando dessa forma:

É importante ressaltar que o nome após 'hint' tem que ser igual ao nome do campo dado anteriormente, agora é só salvar.

Ao criar um novo card, basta selecionar esse tipo no local onde ficaria ‘Básico’. O visual de criação ficará assim:

Com estas configurações, durante a revisão seus cartões vão ficar dessa forma:

Ao clicar em ‘Frase de contexto’ vai aparecer a frase

E ao clicar em mostrar resposta, será mostrada a tradução.

Não posso afirmar que essa é a melhor prática para melhorar o vocabulário de inglês com anki, mas é a forma como eu gosto de aprender.

Configurando Prisma ORM no Nestjs usando Singleton Pattern

jacksonPrimo — Sun, 24 Dec 2023 17:54:38 +0000

Configurando o prisma no nestJs seguindo a risca a documentação traz um problema relacionado a abertura de conexões com o banco, ao executar o projeto localmente não há grandes desvantagens nisto, no entanto ao usar um banco online como o caso do ElephantSql ou Supabase que possuem limites de conexões abertas isto vem a se tornar um grande impecilho.

Como consequencia recebemos constantes erros como este:

Error querying the database: db error: FATAL: too many connections for role "qcjoaamjgbnxjx"

Isto ocorre devido a cada modulo abrir uma ou mais conexões e não encerrar ao fim da query. Para resolver, precisariamos ter uma forma de chamar a mesma instancia do prisma todas nossas querys, é aqui que aplicamos o padrão singleton.

Começamos iniciando nosso projeto:

$ npm install -g @nestjs/cli
$ nest new project_name

Em seguida configuramos o prisma:

$ yarn add @prisma/client
$ yarn add prisma --dev
$ yarn prisma init

Agora vamos precisar do nosso modulo singleton para o prisma, para isso iniciaremos um novo service:

$ yarn nest g s modules/services/prisma

Vamos fazer com que este service extenda a classe do prisma e sempre que chamar seu construtor, pegar a mesma instância armazenada em uma variável estática:

import { Injectable } from '@nestjs/common';
import { PrismaClient } from '@prisma/client';

@Injectable()
export class PrismaService extends PrismaClient {
  private static instance: PrismaClient;

  public static getInstance(): PrismaClient {
    if (!PrismaService.instance) {
      PrismaService.instance = new PrismaClient();
    }

    return PrismaService.instance;
  }
}

Para utilizarmos este service em nossos modulos precisamos adicionar ele dentro dos providers do modulo desejado:

import { Module } from '@nestjs/common';
import { PrismaService } from './services/prisma/prisma.service';

@Module({
  imports: [],
  controllers: [],
  providers: [
    {
      provide: PrismaService,
      useValue: PrismaService.getInstance(),
    },
  ],
})
export class ExempleModule {}

Exemplo de uso:

import { Controller, Get } from '@nestjs/common';
import { PrismaService } from './services/prisma/prisma.service';

@Controller()
export class ExempleController {
  constructor(private readonly prisma: PrismaService) {}

  @Get()
  async exemple(): Promise<any> {
    const newUser = await this.prisma.user.create({ email: '', name: '' });
    return newUser;
  }
}

Referências:
https://engcfraposo.medium.com/aplicando-o-padrão-singleton-no-nestjs-999af3d86c6d

https://docs.nestjs.com/recipes/prisma

Autenticação JWT em uma Api Rest Ruby On Rails

jacksonPrimo — Thu, 22 Jun 2023 00:42:04 +0000

Neste artigo vou mostrar como implementar um autenticação jwt seguindo uma arquitetura um pouco fora da curva do que as docs do rails ensina.

Eu sou uma pessoa em processo de adaptação ao rails, então procurando por tutoriais na internet quase sempre me deparo apenas com exemplos simples, onde tudo é resolvido nos controllers, algo que me incomoda muito pois eu sei que conforme o projeto cresce as regras de negócio passam a ser muito mais complexas que um simples MVP de um blog, logo logo esses controllers vão ficar enormes, resolvi fazer uso então de UseCases para guardar as regras de negócio como veremos mais para frente.

O setup inicial do projeto segue o desse artigo a parte:
https://dev.to/jackson_primo/inicializando-um-projeto-ruby-on-rails-usando-postgresql-docker-compose-1gh5

Let's Bora

Começaremos adicionando nosso model de User na nossa aplicação, afinal ele será o foco da autenticação:

$ rails g model user name:string username:string email:string password_digest:string

Este comando irá criar uma nova migration dentro da pasta db/migrations, nele irá ter os comandos de criação da tabela User.

class CreateUsers < ActiveRecord::Migration[7.0]
  def change
    create_table :users do |t|
      t.string :name
      t.string :email
      t.string :password_digest

      t.timestamps
    end
  end
end

Para rodar essa migration e fazer o banco receber as atualizações dos models da aplicação usamos o comando abaixo.

$ rails db:migrate

Após atualizar o banco será criado ou atualizado também um arquivo db/schema.rb que irá conter a estrutura das tabelas.

ActiveRecord::Schema[7.0].define(version: 2024_08_21_003305) do
  enable_extension "plpgsql"

  create_table "users", force: :cascade do |t|
    t.string "name"
    t.string "email"
    t.string "password_digest"
    t.datetime "created_at", null: false
    t.datetime "updated_at", null: false
  end

end

Agora vamos adicionar algumas modificações no model:

class User < ApplicationRecord
  has_secure_password
  validates :email, format: {with: URI::MailTo::EMAIL_REGEXP}, presence: true, uniqueness: true
  validates :name, presence: true, length: { maximum: 50 }
  validates :password, presence: true, length: { minimum: 6 }

  before_save :downcase_email

  private

  def downcase_email
    self.email = email.downcase
  end
end

Na segunda linha temos o has_secure_password, que adiciona recursos de autenticação nativos do rails no model, como a criação do campo password_digest que abriga o password encriptado e o método authenticate no model que verifica se uma string corresponde ao password encriptado.

Com nosso model pronto vamos configurar os controllers, primeiramente adicionando alguns métodos no application_controller, que vai ser herdado por todos os outros controllers:

class ApplicationController < ActionController::API
  def render_result result
    if result.is_a?(Hash) && result[:error]
      render json: { error: result[:error] }, status: result[:code]
    else
      render json: result
    end
  end

  def params 
    request.params
  end
end

Vamos gerar o controller que ficará responsável pela autenticação.

$ rails g controller auth signin signup

Nele colocaremos 2 métodos, um de registro e outro de login.

class AuthController < ApplicationController
  def signin
    result = ::UseCases::Auth::Signin.new(params).call
    render_result result
  end

  def signup
    result = ::UseCases::Auth::Signup.new(params).call
    render_result result
  end
end

Note que em cada função decidi deixar as regras de negócio para um arquivo a parte que seriam os UseCases.
Ps: Antes de prosseguirmos uma breve explicação sobre os UseCases, o uso deles a meu ver representa bem o uso do principio Single Responsability do SOLID, pois cada arquivo representa apenas uma ação que deve ser executada, possuindo um nome que reflete esta ação e apenas um método público "call". Elas serão adicionadas dentro de app -> use_cases e cada pasta dentro dela representa um módulo que trata de um conjunto de regras de negócio, podendo ser de uma funcionalidade ou apenas de um model no banco.

Vamos criar o modulo de useCase chamado Auth, começando pela classe base que é responsável por abrigar funções e variáveis que podem ser reaproveitadas por outros arquivos dentro do modulo.

# app/use_cases/base.rb
module UseCases
  class CustomException < Exception
    attr_reader :code

    def initialize(message, error_code=500)
      super(message)
      @code = error_code
    end
  end

  class Base
    def initialize(params)
      @params = params
    end
  end
end

Inicialmente ela só vai pegar os parâmetros da request e jogar em uma variável de instancia, também adicionei uma classe chamada CustomException para tratar exceções aceitando a mensagem e o código de erro.

Agora vamos criar nosso signin:

module UseCases
  module Auth
    class Signin < Base
      include AuthHelper

      def call
        find_user
        authenticate
      rescue ::UseCases::CustomException => e
        { error: e.message, code: e.code }
      rescue Exception => e
        { error: e.message, code: 500 }
      end

      def find_user
        @user = ::User.find_by_email(@params[:email])
      end

      def authenticate 
        if @user&.authenticate(@params[:password])
          encode_token(@user)
        else
          raise ::UseCases::CustomException.new("password or email incorrect", 403)
        end
      end
    end
  end
end

A função authenticate @user vem do has_secure_password adicionado no model.
Agora partimos para o signup:

module UseCases
  module Auth
    class Signup < Base
      include AuthHelper

      def call
        already_has_user_with_this_email?
        user = create_user
        encode_token(user)
      rescue ::UseCases::CustomException => e
        { error: e.message, code: e.code }
      rescue Exception => e
        { error: e.message, code: 500 }
      end

      def already_has_user_with_this_email?
        user = ::User.find_by_email(@params[:email])
        raise ::UseCases::CustomException.new('email already in use', 400) if user 
      end

      def create_user
        user = User.new(sanitize_params)
        return user if user.save!
        raise ::CustomException.new("cannot register user: #{user.errors}", 400)
      end

      def sanitize_params
        @params.slice(:name, :password, :email)
      end
    end
  end
end

Note que em ambos UseCases temos a função encode_token, ela vem do helper AuthHelper incluido no início da classe. Vamos implementar ele:

$ rails g helper auth

# app/helpers/auth_helper.rb
require "jwt"

module AuthHelper
  def encode_token user
    exp = 3.days.from_now
    token = JWT.encode({ user_id: @user.id, exp: exp.to_i }, ENV['JWT_SECRET'], "HS256")

    { token: token, exp: exp }    
  end
end

A função encode_token usa a lib JWT para gerar um hash baseado no payload(composto pelo id do usuário e um tempo de expiração de 3 dias) e no secret que está em uma variável de ambiente. Para instalar a lib adicione a seguinte linha no seu Gemfile:

gem 'jwt', '~> 1.5', '>= 1.5.4'

E execute:

$ bundler install

Para finalizar vamos fazer um middleware para cuidar da verificação de autenticação de rotas. Para isso vamos adicionar uma função no nosso application_controller.rb chamada authenticate_user:

class ApplicationController < ActionController::Base
  include AuthHelper

  {...}

  def authenticate_user
    token = request.headers['Authorization']&.split(' ')&.last
    decoded_token = decode_token(token)
    user_id = decoded_token['user_id']
    user = User.find_by id: user_id
    request.params.merge!(session_user: user)
  rescue JWT::ExpiredSignature
    render json: { error: "token expirado" }, status: 403
  rescue JWT::DecodeError
    render json: { error: "token inválido" }, status: 403
  end
end

Esta função recupera o token do header Authorization e usa a função decode do AuthHelper para validar e decodificar ele. Por fim recupera o usuário no banco e mergeia nos parametros da request.

Para implementar o decode no AuthHelper é bem simples:

  def decode_token token
    JWT.decode(token, ENV['JWT_SECRET'])[0]
  end

Vamos usar este middleware em um segundo controller de teste.

$ rails g controller user

class UserController < ApplicationController
  before_action :authenticate_user

  def get_info
    data = params[:session_user].slice(:name, :email, :created_at)
    render json: { user: data }, status: 200
  end
end

Se quiser que o middleware seja apenas para essa rota, pode usar o only.

before_action :authenticate_user, only: %i[get_info]

E por fim caso queira pular esse middleware use o skip_before_action.

skip_before_action :authenticate_user, only: %i[get_info]

Caso você venha a ter problemas do tipo "NameError: uninitialized constant AuthController::UseCases" é provável que o auto import das configurações esteja seguindo as novas regras de nomenclatura de pastas(uma frescura ae do rails que não sei o motivo de existir), para evitar esse problema adicione a config:

# config/application.rb
config.eager_load_paths.delete("#{Rails.root}/app/use_cases")
config.eager_load_paths.unshift("#{Rails.root}/app")

Nas referências tem um artigo que explica melhor sobre isso.

Com isso temos uma estrutura de pastas e separação de regras de negócio bem interessante. Qualquer dica, sugestão ou duvida deixa nos comentários.

link de referências do artigo:
https://www.toptal.com/ruby-on-rails/rails-service-objects-tutorial
https://blog.appsignal.com/2020/06/17/using-service-objects-in-ruby-on-rails.html
https://www.fastruby.io/blog/rails/upgrade/zeitwerk/upgrading-to-zeitwerk.html
https://dev.to/joker666/ruby-on-rails-pattern-service-objects-b19
https://www.thoughtco.com/nameerror-uninitialized-2907928
https://medium.com/binar-academy/rails-api-jwt-authentication-a04503ea3248

Inicializando um projeto Ruby on Rails usando PostgreSql rodando em um container Docker

jacksonPrimo — Sun, 04 Jun 2023 17:01:48 +0000

Primeiramente inicializamos o projeto.

$ rails new project_name --database=postgresql

Em seguida configuramos o docker-compose.yml

version: '3.8'
services:
  database:
    container_name: project_name
    image: postgres
    restart: always
    environment:
      POSTGRES_USER: root
      POSTGRES_PASSWORD: root
      POSTGRES_DB: project_name_development
    volumes:
      - ./tmp/db:/var/lib/postgresql/data
    ports:
      - '5432:5432'

  adminer:
    container_name: adminer
    image: adminer
    restart: always
    ports:
      - "8080:8080"

ps: Eu particularmente gosto de usar o adminer para visualizar as tabelas do banco, então essa imagem é opcional, para acessar ele basta entrar no endereço: localhost:8080, e colocar as credenciais:
sistem: PostgreSql
host: database
user: root
password: root

Em seguida configuramos o arquivo de configuração do banco de dados para o ambiente de desenvolvimento.

# config/database.yml
development:
  <<: *default
  host: localhost
  database: project_name_development
  username: root
  password: root
  port: 5432

Para testarmos basta criarmos um novo model e uma migration.

$ rails g model User email: string

E por fim rodar a migration que vai persistir as mudanças no banco.

$ rails db:migrate

problemas na conexão do postgres caso o projeto esteja rodando no wsl

Atualmente é possível instalar o docker no windows e o wsl se comunicar com os containers dele, no entanto isso pode causar alguns problemas quando uma aplicação rodando dentro do wsl tenta se comunicar com um banco rodando em um container docker dentro do windows. Existem algumas saídas para este tipo de caso.

Primeiro passo

Uma das primeiras coisas a serem feitas é trocar o host da string de conexão por host.docker.internal, pois o localhost do linux dentro do wsl reflete apenas a propria rede e não a do windows que é onde está rodando o container do docker.

host.docker.internal busca o ip correto do container dentro do windows(no caso do wsl é o ip do proprio windows)

Segundo passo

permitir que o wsl abra uma conexão para o windows criando uma regra no firewall:

Você precisa permitir explicitamente que aplicações (como o WSL) se conectem à porta 5432 no seu computador.

Abra o Firewall do Windows:
- Pressione a tecla Windows, digite "Firewall" e selecione "Windows Defender Firewall com Segurança Avançada".
Crie uma Nova Regra de Entrada:
- No painel esquerdo, clique em "Regras de Entrada".
- No painel direito, clique em "Nova Regra...".
Configure a Regra:
- Tipo de Regra: Selecione "Porta" e clique em "Avançar".
- Protocolo e Portas: Selecione "TCP" e em "Portas locais específicas", digite 5432. Clique em "Avançar".
- Ação: Selecione "Permitir a conexão" e clique em "Avançar".
- Perfil: Deixe as três opções marcadas (Domínio, Particular, Público) para garantir que funcione em qualquer rede. Clique em "Avançar".
- Nome: Dê um nome fácil de lembrar, como Docker Postgres WSL, e uma descrição se quiser. Clique em "Concluir".

Configurando Nestjs com Firebase Admin

jacksonPrimo — Thu, 02 Sep 2021 03:37:33 +0000

NestJs

Nestjs é um framework voltado para construção de aplicações nodejs de forma performática e escalável. Possui suporte a diferentes paradígmas de programação tais como programação orientada a objetos e funcional dando um toque de flexibilidade na hora de codar.

Firebase

O firebase é um Backend as a Service(BaaS), uma série de serviços em nuvem que abstraem taréfas repetitivas e pesadas para desenvolvedores tais como autenticação de usuário, armazenamento de dados dentre outros.

Lets Bora

Para iniciarmos um projeto nest usamos os seguintes comandos:

npm i -g @nestjs/cli //para instalar o nest cli de forma global
nest new project-name //para criar um projeto

Ele vai pergutar qual gerenciador de pacotes deseja usar, no meu caso vou usar o yarn:

 Which package manager would you ❤️  to use?
  npm
> yarn
  pnpm

Instale o firebase-admin:

yarn add firebase-admin
//ou
npm i firebase-admin

Instale o dotenv para que os dados sensiveis do firebase sejam gravados em variáveis de ambiente e assim tornar mais segura estas informações:

yarn add dotenv
//ou
npm i dotenv

No arquivo main.ts na pasta src inicialize o dotenv:

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import * as dotenv from 'dotenv';

dotenv.config();

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  await app.listen(process.env.PORT || 3000);
}
bootstrap();

Dentro da pasta src crie um arquivo chamado firebase.config.ts, com as seguintes informações:

import * as firebase from 'firebase-admin';

export function initializeFirebase() {
    var serviceAccount = JSON.parse(process.env.FIREBASE);
    firebase.initializeApp({
        credential: firebase.credential.cert(serviceAccount),
        databaseURL: "https://exemplo-app.firebaseio.com"
    });
}

Importamos todo conteúdo de firebase-admin e nomeamos como firebase
exportamos a função que irá inicializar a conexão
pegamos as credênciais de uma variável de ambiente, que está em formato json e transformamos em um objeto com JSON.parse()
chamamos as função firebase.initializeApp() passando as credenciais

Para obtermos as credenciais temos que ir no nosso projeto do firebase e em:

configuração do projeto

contas de serviço

gerar nova chave privada

Será iniciado o download de um arquivo JSON que conterá informações confidenciais do projeto usadas para fazer a integração, portanto tome cuidado onde deixa este arquivo e se possível o exclua após pegar suas informações. Ele terá as seguintes informações:

{
 "type": "service_account", 
 "project_id": "exemplo-app", 
 "private_key_id": "000000000000000000000000000000000000", 
 "private_key": "-----BEGIN PRIVATE KEY-----varias letras aleatórias-----END PRIVATE KEY-----\n", 
 "client_email": "firebase-adminsdk-xxx@exemplo-app.iam.gserviceaccount.com", 
 "client_id": "000000000000000", 
 "auth_uri": "https://accounts.google.comxxxxxx", 
 "token_uri": "https://xxxx.googleapis.com/token", 
 "auth_provider_x509_cert_url":"https://www.googleapis.com/xxx", 
 "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/xxxxgserviceaccount.com"
}

Crie um arquivo .env na raiz de seu projeto e dentro dele crie uma variável de ambiente chamada FIREBASE, você deve setar seu valor colocando todas as credenciais do arquivo json em apenas uma linha:

//.env
FIREBASE={"type": "service_account", "project_id": "exemplo-app", "private_key_id": "000000000000000000000000000000000000", "private_key": "-----BEGIN PRIVATE KEY-----varias letras aleatórias-----END PRIVATE KEY-----\n", "client_email": "firebase-adminsdk-xxx@exemplo-app.iam.gserviceaccount.com", "client_id": "000000000000000", "auth_uri": "https://accounts.google.comxxxxxx", "token_uri": "https://xxxx.googleapis.com/token","auth_provider_x509_cert_url":"https://www.googleapis.com/xxx", "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/xxxxgserviceaccount.com"}

Novamente no arquivo main.ts na pasta src, inicialize o firebaseConfig:

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import * as dotenv from 'dotenv';
import { initializeFirebase } from './firebase.config';

dotenv.config();
initializeFirebase();

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  await app.listen(process.env.PORT || 3000);
}
bootstrap();

Podemos testar nossa integração criando um arquivo user.repository.ts dentro da pasta "src/repositorys":

import { Injectable } from "@nestjs/common";
import * as firebase from 'firebase-admin';
@Injectable()
export class UserRepository {
    private _collectionRef: FirebaseFirestore.CollectionReference = firebase.firestore().collection('user');
    public async getUser(UserId: string): Promise<any> {
         return this._collectionRef.doc(UserId).get();
    }
}

finalizando

Bom com esta configuração você poderá gravar dados no banco do firebase, atualizar ou apagar dados de autenticação de usuário tais como senhas e emails etc. É isso, obrigado por lerem este artigo e espero que ele tenha os ajudado! :)
(caso não: coloque mais café na chicara e não desanime!).