Forem: Leandro Lima

Demystifying CPF and CNPJ Check Digit Algorithms: A Clear and Concise Approach

Leandro Lima — Mon, 02 Sep 2024 21:56:50 +0000

I vividly rememeber my first encounter with the CPF (Brazillian ID) validation algorihm during my underagraduated studies. While applying for an internship at the Institute of Exact Sciences at UFMG, the Federal University of Minas Gerais, we were asked to write a Java code, by hand, to validate CPF check digits after a brief explanation of the algorithm.

Since then, I've come across this problem several times in different professional contexts, often resorting to copying solutions from the internet and adding some unit tests. However, each time, I'm struck by the recurring issues in these solutions. They tend to be more rooted in an imperative paradigm than the exptected object-oriented approach for Java codes. But, what bothers me even more, the high cognitive load these implementations impose that turns impratical to read, and understand the code's intent.

An interested developer who hasn't yet needed to implement this code can easily find solutions in any programming language. However, they all tend to be presented the same way: a naive replication of the explanation for how the CPF check digits are implemented. It seems that few people take the time to understand the reasoning behind this approach.

The collision problem

In software development, the concept of collision avoidance is often encountered in hash code algorithms, particularly with the use of prime number modulus. The check digits in CPF (Brazillian ID) and CNPJ (Brazillian company ID) function similarly, fucusing on avoiding collisions. This ensures that a simple summation of digits doesn't mistakenly validate incorrect entries, as multiple combinations can produce the same sum.

To mitigate this, a common practice is to apply weighted sums, miltiplying each digit by a specific factor. You can think of this as spreading the digits out along a line; the multiplication makes it less likely for multiple digits land in the same position. It makes sense, then, that the digit's position in the number determines its weight.

To further enhance reliability and minimize the risk of collisions, the sum is taken modulo 11, and this result is subtracted from the same prime number. To ensure that the check digit remains a single digit, results of 10 and 11 are converted to 0.

The cognitive load

The algorithm used to calculate the check digits for CPF and CNPJ can be difficult to understand. While the overall motivation behind the algorithm might be clear, it's ofen challenging to grasp the specific role of each part. This complexit arises partly because the caculation involves a series of mathematical computations that are often lumped together in a single, large method. Additionally, the weights, tipically presented as an inexplicable array, can appear illogical.

To combat this, I focus on reducing the amount of code that laks self-explanation. By adhering to the Single Responsability Principal (the "S" in SOLID), I strive to create simpler, more understandlable methods. I also make an effor to define key concepts through meaningful variable names, aiming to establish a ubiquitous language within the codebase. With this approach, I sought to identify what differentiates the method used for CPF check digits from that used for CNPJ, as software that requires one often needs the other. The core functionality of the code is showed below, also, for a further view, including the complete code and associated unit tests, please visit my GitHub repository.

  private String getCheckDigits(String document, int maxWeight) {
    final int lengthWithoutCheckDigits = getBaseDigitsLength(document);

    int firstWeightedSum = 0;
    int secondWeightedSum = 0;
    for (int i = 0; i < lengthWithoutCheckDigits; i++) {
      final int digit = Character.getNumericValue(document.charAt(i));
      final int maxIndex = lengthWithoutCheckDigits - 1;
      final int reverseIndex = maxIndex - i;
      firstWeightedSum += digit * calculateWeight(reverseIndex, maxWeight);
      // Index is incremented, starting from 3, skipping first check digit.
      // The first part will be added later as the calculated first check digit times its corresponding weight.
      secondWeightedSum += digit * calculateWeight(reverseIndex + 1, maxWeight);
    }

    final int firstDigit = getCheckDigit(firstWeightedSum);
    // Add the first part as the first check digit times the first weight.
    secondWeightedSum += MIN_WEIGHT * firstDigit;
    final int secondDigit = getCheckDigit(secondWeightedSum);

    return String.valueOf(firstDigit) + secondDigit;
  }

  private int calculateWeight(int complementaryIndex, int maxWeight) {
    return complementaryIndex % (maxWeight - 1) + MIN_WEIGHT;
  }

  private int getCheckDigit(int weightedSum) {
    final var checkDigit = enhanceCollisionAvoidance(weightedSum);
    return checkDigit > 9 ? 0 : checkDigit;
  }

  private int enhanceCollisionAvoidance(int weightedSum) {
    final var weightSumLimit = 11;
    return weightSumLimit - weightedSum % weightSumLimit;
  }

Compare the result that calculates check digits for both CNPJ and CPF with the tipical solution found in Internet:

public class ValidaCNPJ {

  public static boolean isCNPJ(String CNPJ) {
// considera-se erro CNPJ's formados por uma sequencia de numeros iguais
    if (CNPJ.equals("00000000000000") || CNPJ.equals("11111111111111") ||
        CNPJ.equals("22222222222222") || CNPJ.equals("33333333333333") ||
        CNPJ.equals("44444444444444") || CNPJ.equals("55555555555555") ||
        CNPJ.equals("66666666666666") || CNPJ.equals("77777777777777") ||
        CNPJ.equals("88888888888888") || CNPJ.equals("99999999999999") ||
       (CNPJ.length() != 14))
       return(false);

    char dig13, dig14;
    int sm, i, r, num, peso;

// "try" - protege o código para eventuais erros de conversao de tipo (int)
    try {
// Calculo do 1o. Digito Verificador
      sm = 0;
      peso = 2;
      for (i=11; i>=0; i--) {
// converte o i-ésimo caractere do CNPJ em um número:
// por exemplo, transforma o caractere '0' no inteiro 0
// (48 eh a posição de '0' na tabela ASCII)
        num = (int)(CNPJ.charAt(i) - 48);
        sm = sm + (num * peso);
        peso = peso + 1;
        if (peso == 10)
           peso = 2;
      }

      r = sm % 11;
      if ((r == 0) || (r == 1))
         dig13 = '0';
      else dig13 = (char)((11-r) + 48);

// Calculo do 2o. Digito Verificador
      sm = 0;
      peso = 2;
      for (i=12; i>=0; i--) {
        num = (int)(CNPJ.charAt(i)- 48);
        sm = sm + (num * peso);
        peso = peso + 1;
        if (peso == 10)
           peso = 2;
      }

      r = sm % 11;
      if ((r == 0) || (r == 1))
         dig14 = '0';
      else dig14 = (char)((11-r) + 48);

// Verifica se os dígitos calculados conferem com os dígitos informados.
      if ((dig13 == CNPJ.charAt(12)) && (dig14 == CNPJ.charAt(13)))
         return(true);
      else return(false);
    } catch (InputMismatchException erro) {
        return(false);
    }
  }
}

This piece of code is just for CNPJ!

Conclusion

While the result code may appear somewhat verbose, my emphasis on clarity and self-explanation led to an outcome that I am satisfied with. The code is designed to be more intuitive, offering greater confidence in its correctness and, also, most of the core functionality is visible without scrolling down the page.

I welcome any suggestions for further improvement, so please feel free to share your feedback.

[Code Compare] 2. Collections.singletonList vs List.of

Leandro Lima — Tue, 06 Aug 2024 23:41:46 +0000

In this serie of posts, I'm comparing different ways to code the same functionality. Last post compared Collections.singletonList and ArrayList for creating a single-element list.

In this post I'll compare Collections.singletonList whith another well-known Factory Method, List.of.

Collections::singletonList

Method signature

public static <T> List<T> singletonList(T o)

  public static void main(String[] args) {
    final var addresses = Collections.singletonList(
        new Address(
            "742 Evergreen Terrace",
            "Springfield",
            "New York",
            "13468",
            "US"
        ));

    System.out.println(addresses);
  }

Description

This method returns an immutable list containing only the specified object. It was introduced in Java 1.3. The advantages over ArrayList were covered in the last post, but to recap:

Inline implementation: Initialize with the desired element in a single line.
Immutability: The list's size and content of its single element cannot be changed.
Memory Allocation: The SingletonList class contains only one field for the single element.
CPU usage: The SingletonList constructor accepts the single element as a parameter, requiring no resizing or array maniputalion.

List::of

Method signature

static <E> List<E> of()

  public static void main(String[] args) {
     final var addresses2 = List.of(
        new Address(
            "1007 Mountain Drive",
            "Bristol Township",
            "New Jersey",
            null,
            "US"
        ));

    System.out.println(addresses2);
  }

Description

The List.of(E e) method is also a Factory Method that returns an unmodifiable list. Unlike Collections.singletonList(E e), which supports only one element, List.of supports 0 to 10 elements, as well as arrays with multiple elements. It was introduced in Java 9, 17 years after singletonList.

It's interesting note that, unlike SingletonList, which has the comment:

Returns an immutable list containing only the specified object.

the Array.of states that it is an Unmodifiable List:

Returns an unmodifiable list containing one element.

This reflects a new understand of immutability of collections. According this documentation:

A collection is considered unmodifiable if elements cannot be added, removed, or replaced. However, an unmodifiable collection is only immutable if the elements contained in the collection are immutable.

Dispite this differences in terminology, both factory methods have almost the same functionality. Looking deeper inside the UnmodifiableList, we can find:

  static <E> List<E> of(E e1) {
      return new ImmutableCollections.List12<>(e1);
  }

What a surprise, they went with the not-so-precise term Immutable, though!

  static final class List12<E> extends     
    AbstractImmutableList<E> implements Serializable {

        @Stable
        private final E e0;

        @Stable
        private final E e1;

        List12(E e0) {
            this.e0 = Objects.requireNonNull(e0);
            this.e1 = null;
        }
        ...
    }

static abstract class AbstractImmutableList<E> extends
  AbstractImmutableCollection<E> implements List<E>, RandomAccess {

      // all mutating methods throw UnsupportedOperationException
      @Override public void    add(int index, E element) { throw uoe(); }
      @Override public boolean addAll(int index, Collection<? extends E> c) { throw uoe(); }
      @Override public E       remove(int index) { throw uoe(); }
      @Override public void    replaceAll(UnaryOperator<E> operator) { throw uoe(); }
      @Override public E       set(int index, E element) { throw uoe(); }
      @Override public void    sort(Comparator<? super E> c) { throw uoe(); }

The only difference is that List12 has two fields for potentially two elements, which also results in a negligible memory footprint unless dealing with large objects.

Conclusion

This time, we compared Collections.singletonList and List.of factory methods to create a single-element list. We discussed about the semantics of immutable and unmodifiable and showed that both methods are efficient, concise, and resource-light. If you can use a more recent Java version, it's prefferable for its familiarity, clarity and because we use List interface much more than Collections. If restritcted to an older Java version, Collections.singletonList remains a solid choice.

[Code Compare] 1. ArrayList vs Collections.singletonList

Leandro Lima — Tue, 06 Aug 2024 02:54:50 +0000

I am starting a new thread to compare different ways to code the same functionality. In this post, I'll compare two common methods to create a simple list with only one element. Specifically, I'll examine the most commonly used List implementation constructor and the Collections.singletonList, a straightforward Factory Method for creating an immutable list containing a single element.

Array List

Everytime you initialize an ArrayList without specifying its initial capacity, it starts with an empty array. When you add the first element, the ArrayList resizes using a relatively havy algorithm that involves copying the array. Let's take a look at the ArrayList structure:


  private static final int DEFAULT_CAPACITY = 10;
  private static final Object[] DEFAULTCAPACITY_EMPTY_ELEMENTDATA = {};

  public ArrayList() {
    this.elementData = DEFAULTCAPACITY_EMPTY_ELEMENTDATA;
  }

  public boolean add(E e) {
    modCount++;
    add(e, elementData, size);
    return true;
  }

  private void add(E e, Object[] elementData, int s) {
    if (s == elementData.length)
        elementData = grow();
    elementData[s] = e;
    size = s + 1;
  }

  private Object[] grow() {
      return grow(size + 1);
  }

  private Object[] grow(int minCapacity) {
    return elementData = Arrays.copyOf(elementData,
                                      newCapacity(minCapacity));
  }

  private int newCapacity(int minCapacity) {
    // overflow-conscious code
    int oldCapacity = elementData.length;
    int newCapacity = oldCapacity + (oldCapacity >> 1);
    if (newCapacity - minCapacity <= 0) {
        if (elementData == DEFAULTCAPACITY_EMPTY_ELEMENTDATA)
            return Math.max(DEFAULT_CAPACITY, minCapacity);
        if (minCapacity < 0) // overflow
            throw new OutOfMemoryError();
        return minCapacity;
    }
    return (newCapacity - MAX_ARRAY_SIZE <= 0)
        ? newCapacity
        : hugeCapacity(minCapacity);
  }

Here's what happens step-by-step:

An initial empty array elementData is created.
When you add the first element, the current size (which is zero) is compared to the length of the array.
Since it found out that the its size is zero, the array needs to grow to accomodate the new element.
The grow method is called, which calculates the new capacity.
The newCapacity is initially increased by half the old capacity, which let us with 0 + 0/2 = 0.
Since newCapacity is not sufficient to accomodate the element, it continues.
As it found out that elementData is the same initial empty array, it finally returns maximum between the required size (1) and the DEFAULT_CAPACTIY (10), resulting in an array of size 10.

This resizing process is quite complex when you only need a simple list that will always contain a single element.

That said, let's talk about our alternative!

Collection::singletonList

Method signature:

public static <T> List<T> singletonList(T o)

Description

This method returns an immutable list containing only the specified object. Introducted in Java 1.3, singletonList has several advantages:

Inline implementation: You can initialize it with the desired element in a single line.

Immutability: Let's take a look at its implementation:

private static class SingletonList<E> extends AbstractList<E>
    implements RandomAccess, Serializable {

  private final E element;

  SingletonList(E obj) {
    element = obj;
  }
  ...
}

The AbstractList, from which SingletonList inherits, defines all mutable methods like this:

  public boolean add(E e) {
    add(size(), e);
    return true;
  }

  public void add(int index, E element) {
    throw new UnsupportedOperationException();
  }

  public E remove(int index) {
    throw new UnsupportedOperationException();
  }

  public E set(int index, E element) {
      throw new UnsupportedOperationException();
  }

This ensures that it's impossible to chante the list's size or the content of its single element.

Immutability is a highly advantageous feature. While I won't delve into it here, interested developers can learn more from this article.

Memory Allocation: The SingletonList class contains only one simple field to accommodate the single element, unlike ArrayList, which uses an array that, using simple ArrayList simple constructor, will leave us with an array with size of 10 after element addition.
CPU usage: The SingletonList constructor accepts the single element as a parameter, requiring no resizing, array copy or maniputalion. This is far more efficient compared to the ArrayList add method.

Conclusion

In this post, we compared two ways to create a simple list with a single element: using the ArrayListconstructor and the Collection.singletonList method. While ArrayList is a flexible and commonly used data structure, it comes with some unnecessary overhead, particularly in terms of memory allocation and CPU usage when adding elements. This overhead includes resizing and copying arrays, which can be redundant for a list that is meant to hold only one element. However, if you need to change this element, ArrayList is a suitable solution.

On the other hand, Collection.singletonList offers a more efficient alternative for creating a single-element list. This method is not only more concise and easier to use but also ensures immutability, which can be a significant advantage in many scenarios. It has a minimal memory footprint and requires almost no CPU resources compared to ArrayList.

In summary, for a simple, immutable list containing only one element, Collection.singletonList is a superior choice due to its efficiency, simplicity, and immutability. However, if you need to modify the element in the list, the ArrayList could be an more appropriate choice.

On the next post I'll compare another alternative for a single-element list: List.of factory method. See you later!

LocalStack: O poder da AWS direto da sua máquina

Leandro Lima — Tue, 14 Jun 2022 21:48:44 +0000

O que você vai ver nesse artigo

AWS services: APIGateway, Lambda, DynamoDB
LocalStack Community
NodeJs
Docker Compose
Terraform

O que vamos fazer

Definição da nossa POC (Proof of Concept)

O objetivo desse artigo é exemplificar o uso da LocalStack e o que é necessário para rodar um projeto simples. Para além do que usamos aqui, a ferramenta possui inúmeros outros recursos, bem como outros serviços ofertados pela AWS, que não abordarei.

Nossa POC é portanto muito simples. Trata-se de uma solução que envolve um APIGateway que recebe requisições para busca, listagem e criação de mensagens de vilões famosos. As requests de criação são tratadas por um Lambda criado com NodeJs que grava essas mensagens em uma fila SQS que por sua vez tem um gatilho para que outro Lambda recupere essa frase e a persista em um banco DynamoDB. Na parte de listagem e detalhamento da mensagem, usamos outro Lambda que busca a mensagem da base de dados e retorna para o usuário.

Toda a configuração da aplicação foi feita usando o Terraform com arquivos de configuração bastante simples de entender.

Repositório

Todo esse projeto e os códigos completos estão disponíveis no seguinte repositório. Este texto contém alguns
pedaços de códigos que podem não estar completos.

TL;DR

Para quem quer um passo-a-passo rápido de como verificar e executar essa POC, continue nessa sessão. Se você prefere uma explicação bastante minuciosa das decisões e formas para alcançar o resultado do projeto, pule para a sessão seguinte.

Preparando o ambiente:

Clone o projeto do repositório;
Instale o Docker a partir da documentação;
Instale o docker-compose:
1. sudo curl -L "https://github.com/docker/compose/releases/download/v2.2.3/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
2. sudo chmod +x /usr/local/bin/docker-compose
Instale o Python seguindo a documentação oficial;
Instale o AWS CLI: página oficial;
Instale o Localstack: sudo python3 -m pip install localstack
Instale o awscli-local: pip install awscli-local
Siga a orientação oficial para instalar o Terraform;
NodeJs:
1. NVM: repositório oficial
2. NodeJs: comando descrito no repositório

Rodando a aplicação:

No diretório raiz execute o comando: docker-compose up -d
No diretório terraform execute:
1. terraform init
2. terraform apply --auto-approve
Para testar:
1. Instale a extensão REST Client para o VSCode;
2. Abra o arquivo test.http
3. Altere a variável API_ID para o id informado na saída do terraform;
4. Clique em send request para envio da request de POST;
5. Verifique os serviços e logs da sua aplicação em https://app.localstack.cloud/;
6. Verifique, após alguns segundos, se a frase está salva na base de dados, enviando a request de GET com o seu vilão favorito.

Matando a aplicação:

Use o comando terraform destroy --auto-approve a partir do diretório terraform para remover os serviços AWS
Do diretório raiz, utilize o comando docker-compose down -v para apagar todos os recursos criados através do docker-compose.

Versão estendida: tudo o que você precisa para criar a sua própria POC

Na sessão anterior, fizemos um passo-a-passo rápido para rodar a aplicação. Nessa sessão vamos ir mais a fundo, e explicar tudo o que for necessário para a criação da sua própria POC, do zero.

Configurando o ambiente

Estou usando uma máquina rodando Ubuntu 20.04.3 LTS. Tudo o que for feito aqui também é possível usando uma máquina Windows ou Mac. Porém, os métodos para instalação mudam.

Docker

Vamos começar instalando o Docker. Segui precisamente a documentação da página oficial para instalação no Ubuntu. Você pode verificar a versão instalada no seu ambiente com o comando docker -v. Para mim, ele retorna: Docker version 20.10.12, build e91ed57.

Docker Compose

Docker Compose foi um pouco mais complicado para instalar. A página do Docker aponta para uma versão muito antiga do compose. Preferi entrar no repositório do github para verificar e alterar o endereço no comando fornecido na página do Docker. Desta forma, executei os seguintes comandos:

sudo curl -L "https://github.com/docker/compose/releases/download/v2.2.3/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

Agora, a versão que tenho do docker-compose instalada é:



    leandro@leandro-desktop ~> docker-compose -v
    Docker Compose version v2.2.3

Python

A LocalStack usa o compilador Python. Assim precisei instalá-lo, além do gerenciador de pacotes. Segui a documentação oficial. Instalei as seguintes versões:



   leandro@leandro-desktop:~$ python3 --version
   Python 3.8.10
   leandro@leandro-desktop:~$ pip --version
   pip 20.0.2 from /usr/lib/python3/dist-packages/pip (python 3.8)

AWS CLI

Para rodar comandos no terminal para acesso aos dados de serviços da AWS, mesmo que na LocalStack, é necessário usar o AWS CLI. Para sua instalação, eu segui o passo a passo informado na página oficial. Verificando a versão, obtive:



leandro@leandro-desktop ~> aws --version
aws-cli/2.4.11 Python/3.8.8 Linux/5.4.0-94-generic exe/x86_64.ubuntu.20 prompt/off

LocalStack

Para instalar o LocalStack eu tentei seguir o repositório oficial que dizia que não deveria ser instalado usando sudo, mas não funcionou. Instalei com o seguinte comando:



   sudo python3 -m pip install localstack

e a versão que tenho instalada é:



leandro@leandro-desktop:~$ LocalStack --version
0.13.3.1

Também instalei o awscli-local com o comando pip install awscli-local.

Terraform

O Terraform é uma ferramenta de código de infraestrutura ou infrastructure as a code. É open source e mantido pela HashCorp. Para instalar, segui a orientação oficial. Após instalado, testei a versão para:



leandro@leandro-desktop:~$ terraform -v
Terraform v1.1.3
on linux_amd64

NodeJs

A escolha de NodeJs para esse tutorial foi bastante concorrida com Python. Mas pesou o conhecimento e a reutilização do JavaScript em front-end. Aqui vai uma análise bem interessante sobre as possíveis linguagens para desenvolvimento para AWS Lambdas.

Para instalar o Node no meu ambiente eu optei por usar o NVM, gerenciador de versão do NodeJs. Esse gerenciador pode ser baixado do repositório oficial. Após instalado o NVM, basta seguir o comando descrito no repositório.

Com isso a versão do Node na minha máquina ficou:



leandro@leandro-desktop:~$ node -v
v16.13.2
leandro@leandro-desktop:~$ npm -v
8.1.2

AWS Cloud

Escolhi abordar os seguintes serviços da AWS:

API Gateway: Permite criar endpoints e associá-los a um back-end.
Cloudwatch: Permite monitorar a aplicação com alarmes e logs.
Lambda: Permite executar uma função sem a necessidade de provisionar ou gerenciar um servidor.
DynamoDB: Banco de dados não relacional, NoSQL, da AWS.
SQS - Simple Queue Service: Como o nome bem informa, é um serviço de filas de mensagens.

As escolhas são baseadas em necessidades pessoais e naquilo que a LocalStack oferece gratuitamente.

LocalStack

Para iniciar nosso projeto, é necessário subir a LocalStack em um container com as configurações adequadas para o ele. Para isso usei o docker-compose e criei um script seguindo a página oficial. Além disso, busquei compreender e alterar alguns pontos, conforme a documentação de configuração. Com isso, meu docker-compose ficou assim:



version: "3.8"

services:
  localstack:
    # Determino o nome do container principal da aplicação.
    container_name: ${LOCALSTACK_DOCKER_NAME-localstack-terraform-tutorial}
    image: localstack/localstack
    network_mode: bridge
    ports:
      - "127.0.0.1:4566:4566"
      - "127.0.0.1:4571:4571"
    environment:
      # Como eu resolvi trocar o nome do container principal eu preciso informar em uma
      # variável de ambiente.
      - MAIN_CONTAINER_NAME=${LOCALSTACK_DOCKER_NAME-localstack-terraform-tutorial}
      # Informo os serviços da AWS que desejo usar.
      - SERVICES=${SERVICES-dynamodb,lambda,apigateway,sqs,cloudwatch}
      # Diretório para salvar dados localmente.
      - DATA_DIR=${DATA_DIR-tmp/localstack/data}
      # Como nossas funções lambda serão executadas. Nesse caso escolho o padrão
      # rodar as funções dentro de containers para cada uma.
      - LAMBDA_EXECUTOR=${LAMBDA_EXECUTOR-docker}
      # Esse parâmetro diz respeito a como a função será passada para o container. 
      # Se ela será montada no container ou será copiada. Nesse caso, escolhi copiar
      # todo o arquivo zip para dentro do container.
      - LAMBDA_REMOTE_DOCKER=true
    volumes:
      - "${TMPDIR:-/tmp}/localstack:/tmp/localstack"
      - "/var/run/docker.sock:/var/run/docker.sock"

Para rodar o docker-compose, utilizei o comando docker-compose up, ele vai subir todo o ambiente. Se quiser continuar a usar o mesmo terminal para outras coisas, adicione o -d de detach. Para finalizar e se desfazer de todo o ambiente, basta rodar o docker-compose down -v. O -v informa que você também quer que os volumes criados sejam excluídos, liberando todos os recursos do computador.

Uma vez em execução, é possível verificar se está tudo funcionando corretamente através da URL http://localhost:4566/health e do dashboard oferecido pela LocalStack.

Terraform

Agora vamos prover os serviços e suas configurações através do Terraform, especificando os recursos em arquivos .tf que coloquei na pasta terraform.
Seguindo a documentação da LocalStack, primeiro declaramos o provider "aws":



provider "aws" {

  access_key = "test"
  secret_key = "test"
  region     = "us-east-1"
  skip_credentials_validation = true
  skip_metadata_api_check     = true
  skip_requesting_account_id  = true

  endpoints {
    apigateway     = var.default_endpoint
    cloudwatch     = var.default_endpoint
    dynamodb       = var.default_endpoint
    iam            = var.default_endpoint
    lambda         = var.default_endpoint
    sqs            = var.default_endpoint
  }
}

Observe que é necessário apontar os serviços da AWS para o LocalStack. Aqui, eu preferi criar uma variável default_endpoint para manter o endereço:



variable "default_endpoint" {
  description = "Endpoint padrão para os serviços AWS local."
  default     = "http://localhost:4566"
  type        = string
}

API

A declaração da api, o recurso quotes e os métodos são bem fáceis de compreender. E tem duas formas de se fazer isso. A primeira, é declarar blocos para cada api, recurso, integração, método:



# Declarando nossa api para acesso de frases e os métodos
resource "aws_api_gateway_rest_api" "quotes" {
  name        = "Quotes"
  description = "Api para consumo e envio de frases para a aplicação."
}

resource "aws_api_gateway_resource" "quotes" {
  rest_api_id = aws_api_gateway_rest_api.quotes.id
  parent_id   = aws_api_gateway_rest_api.quotes.root_resource_id
  path_part   = "quotes"
}

resource "aws_api_gateway_method" "get_quotes" {
  rest_api_id   = aws_api_gateway_rest_api.quotes.id
  resource_id   = aws_api_gateway_resource.quotes.id
  http_method   = "GET"
  authorization = "NONE"
}

resource "aws_api_gateway_method" "post_quote" {
  rest_api_id   = aws_api_gateway_rest_api.quotes.id
  resource_id   = aws_api_gateway_resource.quotes.id
  http_method   = "POST"
  authorization = "NONE"
}

resource "aws_api_gateway_integration" "quote_receiver" {
  rest_api_id             = aws_api_gateway_rest_api.quotes.id
  resource_id             = aws_api_gateway_resource.quotes.id
  http_method             = aws_api_gateway_method.post_quote.http_method
  integration_http_method = "POST"
  type                    = "AWS_PROXY"
  uri                     = aws_lambda_function.quote_receiver.invoke_arn
}

resource "aws_api_gateway_deployment" "quotes" {
  rest_api_id = aws_api_gateway_rest_api.quotes.id
  stage_name  = "dev"
}

Uma forma mais interessante de fazer isso é usando o OpenAPI para declarar nossa api. Com isso, o nosso arquivo rest-api.tf fica bem mais simples:



resource "aws_api_gateway_rest_api" "quotes" {
  name = "Quotes API"
  body = templatefile("./openapi.json",
    {
      quote_receiver = "${aws_lambda_function.quote_receiver.invoke_arn}",
      quote_recover  = "${aws_lambda_function.quote_recover.invoke_arn}"
    }
  )
}

resource "aws_api_gateway_deployment" "quotes" {
  rest_api_id = aws_api_gateway_rest_api.quotes.id
}

resource "aws_api_gateway_stage" "quotes" {
  deployment_id = aws_api_gateway_deployment.quotes.id
  rest_api_id   = aws_api_gateway_rest_api.quotes.id
  stage_name    = "dev"
}

Eu prefiro declarar o OpenApi usando yaml, mas, por alguma razão, o Terraform não aceita yaml na sua definição do body. Por isso, instalei a extensão openapi-designer que compila os arquivos yaml para um único arquivo json. Minha definição para a API ficou assim:



openapi: 3.0.3
info:
  title: Quotes Api
  description: Api para consumo e envio de frases para a aplicação.
  version: "1.0"
paths:
  /quotes:
    post:
      summary: Permite gravar uma nova frase vilanesca!
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Quote"
      x-amazon-apigateway-auth:
        type: none
      x-amazon-apigateway-integration:
        uri: ${quote_receiver}
        httpMethod: POST
        type: AWS_PROXY
      responses:
        "201":
          description: Frase vilanesca gravada com sucesso!
    get:
      summary: Retorna as frases vilanesca de um vilão.
      parameters:
        - name: author
          in: query
          required: true
          description: O grade vilão por trás das frases.
          schema:
            type: string
      x-amazon-apigateway-auth:
        type: none
      x-amazon-apigateway-integration:
        uri: ${quote_recover}
        httpMethod: POST
        type: AWS_PROXY
      responses:
        "200":
          description: As frases vilanescas para o vilão selecionado.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Quote"

Nossa API, portanto, tem um recurso quote que é disponível no path de /quotes e permite os métodos POST e GET sem necessidade de qualquer autorização de acesso.

Como vimos em nosso diagrama, o objetivo do projeto é que as frases enviadas sejam enviadas para uma fila por uma função Lambda e depois recuperada por outra função e gravada no banco de dados. Aqui, já declaramos a integração também com a função lambda. Vale notar:

Observe que a integração agora é passada como parte do método através da propriedade x-amazon-apigateway-integration. O mesmo para a authorization com a propriedade x-amazon-apigateway-auth.
O Terraform trata o arquivo pelo método templatefile que troca os valores como ${quote_receiver} pelo valor passado como parâmetro.
integration_http_method tem que ser do tipo POST para integração com Lambda. Ele informa como a api vai interagir com o backend;
type deve ser, no nosso caso, AWS_PROXY. Isso permite que a integração chame um recurso da AWS, no nosso caso a Lambda, e passe a request para a Lambda tratar.
No arquivo yaml acima, observe que falta a parte de components, que pode ser encontrada no repositório.

Lambdas

Para receber a mensagem da API, declaramos no nosso lambda.tf:



# Lambdas para processar as frases
data "archive_file" "quote_receiver" {
  type        = "zip"
  output_path = "../lambdas/dist/quote_receiver.zip"
  source_dir  = "../lambdas/quote-receiver/"
}

resource "aws_lambda_function" "quote_receiver" {
  function_name    = "quote_receiver"
  filename         = data.archive_file.quote_receiver.output_path
  source_code_hash = data.archive_file.quote_receiver.output_base64sha256
  handler          = "index.handler"
  runtime          = "nodejs14.x"
  role             = "fake_role"
  environment {
    variables = {
      SQS_URL = "${resource.aws_sqs_queue.quotes.url}"
    }
  }
}

---
resource "aws_lambda_event_source_mapping" "quotes" {
  event_source_arn = aws_sqs_queue.quotes.arn
  function_name    = aws_lambda_function.quote_persister.arn
}

Geramos aqui um arquivo que foi criado na execução do terraform a partir da compactação dos dados dentro da pasta lambdas/quote-receiver. O arquivo compactado é referenciado na criação da função. O mesmo ocorre para nossas outras funções, de persistência dos dados e de recuperação.

Como é possível notar, temos um mapeamento da função quote_persister com a fila SQS. Isso nos permite receber eventos com as informações inseridas na fila sempre que forem adicionadas novas mensagens à ela.

Um ponto interessante é que é possível passar variáveis de ambiente para a função, como é visto na passagem da variável SQS_URL.

Fila SQS

Declarar a fila também é muito simples:



resource "aws_sqs_queue" "quotes" {
    name = "Quotes"
}

DynamoDB

O provisionamento de uma tabela nova no dynamo demanda apenas os campos a seguir:



resource "aws_dynamodb_table" "quotes" {
    name = "Quotes"
    hash_key = "author"
    billing_mode = "PAY_PER_REQUEST"
    attribute {
      name = "author"
      type = "S"
    }
}

Poderíamos informar os demais atributos, mas apenas hash_key é obrigatória.
Esse atributo é equivalente para a AWS ao partition key. Caso eu desejasse criar uma sort key eu deveria passá-la como
range_key e também informar os dados do atributo. No código exemplo usei sort key para me permitir usar frases diferentes
do mesmo autor.

Código

Temos apenas três funções muito simples escritas usando NodeJs: uma para receber quotes, uma para persistir e outra para recuperar. Os códigos completos estão no repositório, mas
vale a pena pontuar alguns detalhes:



const { DynamoDBClient, BatchWriteItemCommand } = require("@aws-sdk/client-dynamodb");
const { Marshaller } = require("@aws/dynamodb-auto-marshaller");


const client = new DynamoDBClient({ endpoint: `http://${process.env.LOCALSTACK_HOSTNAME}:4566` });
const marshaller = new Marshaller();
exports.save = (quotes) => client.send(new BatchWriteItemCommand({
    RequestItems: {
        "Quotes": quotes
            .map(quote => marshaller.marshallItem(quote))
            .map(item => new Object({ PutRequest: { Item: item } }))
    }
}));

O código para persistência de dados no Dynamo mostra o uso da SDK para JavaScript V3.
Diferente da V2, essa versão permite importar apenas módulos que realmente serão necessários para a aplicação, deixando a Lambda muito mais leve.
É necessário configurar o endpoint para os serviços da AWS.
Usei a biblioteca Marshaller que é um mapper entre valores nativos JavaScript e AttributeValues do DynamoDB.
A melhor forma de ver logs da aplicação é pelo dashboard da LocalStack.

Rodando nossa aplicação

Uma vez que o ambiente está rodando através do docker-compose, podemos entrar na pasta terraform e executar o comando terraform init. Este comando irá criar uma pasta .terraform e outros arquivos no projeto. Quando terminado é a vez do comando terraform apply --auto-approve que realmente provisiona todos os recurso que declaramos no nossos arquivos .tf. Ao final, o comando irá disponibilizar como retorno a API_ID, necessária para testarmos a api em um http client.

Assim que a aplicação subir, podemos testar sua funcionalidade com a collection de requests disponível no arquivo test.http. Para rodar os testes nesse arquivo é necessário ter instalada a extensão REST Client para o Visual Studio Code. Uma vez instalada, troque o valor da variável @API_ID para aquele retornado pelo terraform e clique em send request.

Para encerrar nossa aplicação, basta rodar o comando docker-compose down -v a partir do diretório raiz do projeto.

Conclusão

A LocalStack é uma ótima ferramenta para rodar a aplicação em ambiente local, durante o desenvolvimento. Ela elimina a preocupação de
se sujar um ambiente compartilhado por mais desenvolvedores ou de se acabar tendo gastos financeiros por uso indevido da AWS, melhorando muito o processo de criação do código. Essas funcionalidades ficam ainda mais
interessantes quando se é um iniciante em Cloud por que não há riscos de se acabar pagando por algo que estava nas entrelinhas.

Um aspecto que não foi abordado mas vale a pena pesquisar são as bibliotecas e integração da LocalStack com testes de integração. É possível rodar testes automatizados sem onerar a cloud.

Crie testes unitários mais amigáveis e mais rapidamente com Spock

Leandro Lima — Mon, 10 Aug 2020 18:57:02 +0000

Testes e especificações quase sempre são uma dor de cabeça para o desenvolvedor. Gastamos muito tempo escrevendo testes, às vezes muito mais tempo do que gastamos com o desenvolvimento. É difícil também nos ater exclusivamente à linguagem do negócio e escrever algo significativo. Bem mais fácil é nos apoiar nos resultados esperados do código. Assim qualquer alternativa para focar no negócio e fazer testes mais rapidamente é válida.

Spock, a ferramenta, é um framework que traz o poder do Groovy para tornar testes em geral mais expressivos, mais rápidos de escrever, mais agradáveis de ler e entender seguindo de maneira mais descritiva os passos de uma especificação de quatro fases.

O objetivo desse artigo é fazer uma varredura superficial das funcionalidades desse framework.

O código usado nesse material está disponível aqui.

Dependências

Criaremos um projeto sem arquétipo através do Maven e adicionaremos o plugin do GMaven, necessário para integrar o Groovy ao Maven, e o Byte Buddy, sem dependências, necessário para criação de Mocks.



<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.leandro</groupId>
    <artifactId>spock-maven-test</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <description>Projeto para estudar como aplicar testes com Spock.</description>

    <properties>
        <maven.compiler.source>11</maven.compiler.source>
        <maven.compiler.target>11</maven.compiler.target>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.spockframework</groupId>
            <artifactId>spock-core</artifactId>
            <version>2.0-M2-groovy-3.0</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter-engine</artifactId>
            <version>5.6.2</version>
            <scope>test</scope>
        </dependency>
        <!-- Byte Buddy permite manipular bytecodes em tempo de execução.
        Isso permite ao Spock criar Mocks sem necessidade de qualquer outra
        biblioteca dedicada. Outra alternativa ao Byte Buddy é a CGLIB. -->
        <dependency>
            <groupId>net.bytebuddy</groupId>
            <artifactId>byte-buddy</artifactId>
            <version>1.10.13</version>
            <scope>test</scope>
        </dependency>
        <!-- Opcional para usar banco de dados H2 -->
        <dependency>
            <groupId>com.h2database</groupId>
            <artifactId>h2</artifactId>
            <version>1.4.200</version>
            <scope>test</scope>
        </dependency>

        <!-- Permite criar relatórios para os testes. -->
        <dependency>
            <groupId>com.athaydes</groupId>
            <artifactId>spock-reports</artifactId>
            <version>2.0-RC2</version>
            <scope>test</scope>
            <!-- Garante não afetar a versão do Groovy/Spock -->
            <exclusions>
                <exclusion>
                    <groupId>*</groupId>
                    <artifactId>*</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
        <!-- Necessário para criar relatórios -->
        <dependency>
            <groupId>org.slf4j</groupId>
            <artifactId>slf4j-api</artifactId>
            <version>1.7.30</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.slf4j</groupId>
            <artifactId>slf4j-simple</artifactId>
            <version>1.7.30</version>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <!-- O GMaven Plus permite código Groovy ser
            compilado e executado em projetos Maven. -->
            <plugin>
                <groupId>org.codehaus.gmavenplus</groupId>
                <artifactId>gmavenplus-plugin</artifactId>
                <version>1.9.0</version>
                <executions>
                    <execution>
                        <goals>
                            <goal>compileTests</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
            <plugin>
                <artifactId>maven-surefire-plugin</artifactId>
                <version>3.0.0-M5</version>
                <configuration>
                    <useFile>false</useFile>
                    <includes>
                        <include>**/*Test.java</include>
                        <include>**/*Spec.java</include>
                    </includes>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

Segue um comparativo entre o Byte Buddy e o CGLIB.

Os testes usando o Spock serão colocados na pasta src/test/groovy*.*

Vamos começar sentindo o gosto do framework criando um teste simples, mas que apresenta um pouco do poder de expressão:



import spock.lang.Specification
import spock.lang.Unroll

class MaxTest extends Specification {
    @Unroll
    def "Verificar se o máximo entre #a e #b é #c"() {
        expect:
        Math.max(a, b) == c

        where:
        a  | b | c
        1  | 2 | 2
        5  | 2 | 5
        0  | 1 | 1
        -1 | 1 | 1
    }
}

Dados três números, a, b e c, desejamos verificar se nossa aplicação, que calcula o máximo entre a e b, retorna c para cada um dos casos na tabela.

Os resultados esperados são esses:

Com o Spock, escrevemos especificações, e para isso, estendemos a classe Specification. Uma especificação é composta de



class Especificacao extends Specification {
  // fields
  // fixture methods
  // feature methods
  // helper methods
}

Fields

São equivalentes aos campos de classes Java, variáveis com escopo de classe. Entretanto, há uma diferença, a inicialização junto da declaração é equivalente a inicia-los dentro de um método anotado com @BeforeEach. O framework faz dessa forma para isolar os métodos. É uma boa prática inicializa os campos no mesmo local da declaração.

Campos são variáveis de escopo de classe com instâncias individuais por escopo de método.

Quando temos objetos muito grandes, que precisam de muito processamento para serem instanciados, é conveniente manter uma instância única e compartilha-la entre os métodos de teste. Para isso, o Spock utiliza a anotação @Shared.

Dessa forma, esperamos que os seguintes testes sejam executados com sucesso:



import spock.lang.Shared
import spock.lang.Specification;

class CamposTest extends Specification {
    def normal = 5
    @Shared shared = 3

    def "Se alterar o valor do campo, deve ser verificável"() {
        given: 'Valor dos campos foram alterados'
        normal = 6
        shared = 4

        expect: 'O novo valor seja observado no resultado'
        normal == 6
        shared == 4
    }

    def "Sem qualquer alteração, mantem o valor do campo alterado anteriormente"() {
        given: 'Não há novas alterações nos campos'
        expect: 'Campo normal deve ter o valor antigo'
        normal == 5
        and: 'Campo shared deve ter o valor definido no método anterior'
        shared == 4
    }
}

Outra possibilidade é usar static final fields. A documentação sugere dar preferência pelo@Shared e deixar esse caso apenas para constantes por uma questão semântica.

Fixture Methods

São responsáveis por configurar o ambiente de testes, inicializando e finalizando os testes. São eles:



// Equivale ao @BeforeAll/@BeforeClass do JUnit. Roda apenas uma vez // antes que os testes se iniciem.
def setupSpec() {}    
// Equivale ao @Before do JUnit. Roda antes de cada método.
def setup() {}    
// Equivale ao @After do JUnit. Roda logo após cada método.    
def cleanup() {}     
// Equivale ao @AfterAll/AfterClass do JUnit. Roda uma única vez ao //término do último teste.
def cleanupSpec() {}

Feature Methods

O coração de tudo! Descrevem a especificação, o comportamento esperado da sua aplicação. São métodos nomeados por frases auto-explicativas e compostos por blocos indicando as fases da especificação:

Fluxo de fases da especificação. Fonte: Spock

GIVEN: onde você faz a inicialização do teste, isto é, inicializa variáveis. Pode estar implícito, ou seja, não precisa ser declarado.
WHEN: representa um estímulo ao teste, uma entrada, uma ação externa. Sempre que acontece um estímulo, esperamos então (then) uma resposta.
THEN: resposta a um estímulo, o que esperar após um bloco when. De fato, esses blocos ocorrem juntos e pode haver mais de um par when/then no método.
Da mesma forma que expect, esse bloco sempre trata de resultado de condições. Vamos tratar de condições mais a frente.
EXPECT: parecido com o then, é mais natural para casos onde não é interessante usar um bloco when. Isso ocorre especialmente em métodos puramente funcionais, isto é, sem efeitos colaterais.
Juntando o estímulo do teste à resposta em uma única expressão, temos uma apresentação mais concisa.
CLEANUP: o local adequado para finalizar o uso de recursos como acesso a arquivos, streams, etc.
WHERE: é utilizado para escrever testes parametrizados. Cada conjunto de dados dentro do bloco where é tratado como um novo teste.

Condições

Explícitas ou implícitas

Condições ou assertions, testam a sua aplicação. Elas podem ser implícitas, dentro dos blocos when/then ou dentro do bloco expect. Tudo declarado dentro desses blocos compõem uma ou mais condições. Elas também podem ser explícitas, fora desses blocos. Para tanto, usa-se a palavra-chave assert, ex.: assert stack.empty.

Exceções

Tratam casos em que se espera uma exceção do código testado. Para testar exceções, usam-se os métodos thrown() e notThrown().



import spock.lang.Specification

import static java.util.Collections.emptyList

class ExcecaoTest extends Specification {

    def "Lançar exceção quando tentar tirar um elemento de uma lista vazia"() {
        given: 'Uma lista vazia'
        def lista = emptyList()

        when: 'Tentar remover um elemento desta lista'
        lista.pop()

        then: 'Deve lançar exceção do tipo NoSuchElementException'
        def e = thrown(NoSuchElementException)
        and: 'Causa deve ser nula'
        e.cause == null
    }

    def "Não lançar exceção quando tentar incluir uma chave nula num mapa"() {
        given: 'Um hashmap'
        def mapa = new HashMap()

        when: 'Tentar inserir um par chave/valor com chave nula'
        mapa.put(null, 1)

        then: 'Não deve ocorrer qualquer exceção'
        noExceptionThrown()
    }

    def "Groovy == equivale a equals em Java e é nullsafe"() {
        when: 'Comparar null com qualquer objeto'
        def isLeiaNula = "General Leia Organa" == null
        def isHanNulo = null == "Han Solo"
        then: 'Deve retornar false e não gerar exceção de null pointer'
        !isLeiaNula && !isHanNulo
        notThrown(NullPointerException)
    }
}

É possível acessar o conteúdo da exceção atribuindo o resultado do método a uma variável, def e = thrown(EmptyStackException) ou ainda, EmptyStackException e = thrown().

Help Methods

Usando outros frameworks de teste unitário é comum adotarmos métodos utilitários para não duplicar código. No Groovy não seria diferente. O exemplo a seguir mostra o poder da linguagem.



import spock.lang.Specification

class HelpMethodsTest extends Specification {

    def "Verificar se email obedece padrão"() {
        expect: 'Meu email fake seja válido!'
        "é um email válido"("leandro@leandro.com.br")
    }

    static def "é um email válido"(email) {
        email.contains('@') && email.endsWith(".com.br")
    }
}

Para identificar melhor onde está o problema, sugere-se usar o assert dentro do método utilitário para cada linha condicional.

Usando o método `with` para verificar campos

O Groovy oferece uma gama muito grande de syntactic sugars que nos permitem deixar o código muito mais simples. Um deles é o método with que permite testar as propriedades de um objeto em poucas linhas até que qualquer dessas propriedades seja falsa. Uma alternativa ao with é o verifyAll que testa todos os campos sem o curto circuito.



import groovy.transform.ToString
import spock.lang.Shared
import spock.lang.Specification
import spock.lang.Unroll

@Unroll
class WithTest extends Specification {

    @Shared
            mulheresImportantes = [
                    "Ada Lovelace",
                    "Grace Hopper",
                    "Margaret Hamilton",
                    "Katie Bouman",
                    "Barbara Liskov"
            ]

    @ToString
    static class PessoasImportanteDaTI {
        String nome
        String sexo
        String descricao
    }


    def "Verificar se #pessoa.nome é uma mulher importante das ciências da computação"() {
        verifyAll(pessoa) {
            nome in mulheresImportantes
            sexo == 'F'
        }

        where:
        pessoa << [
                new PessoasImportanteDaTI(
                        nome: "Ada Lovelace",
                        sexo: 'F',
                        descricao: "Escreveu o primeiro algoritmo\
                    para ser processado por uma máquina. "),
                new PessoasImportanteDaTI(
                        nome: "Grace Hopper",
                        sexo: 'F',
                        descricao: "Criou uma linguagem que foi a \
                    base para o COBOL."),
                new PessoasImportanteDaTI(
                        nome: "Katie Bouman",
                        sexo: 'F',
                        descricao: "Criou algotimos para processar \
                    a primeira imagem de um buraco negro."),
                new PessoasImportanteDaTI(
                        nome: "Barbara Liskov",
                        sexo: 'F',
                        descricao: "Criou o Princípio da Substituição de Liskov, \
                    foi a primeira mulher a obter um PhD em Ciência da Computação \
                    nos Estados Unidos e inventou o Tipo Abstrato de Dado."),
                new PessoasImportanteDaTI(
                        nome: "Margaret Hamilton",
                        sexo: 'F',
                        descricao: "Desenvolveu o programa de voo usado no projeto Apollo 11."),
                new PessoasImportanteDaTI(
                        nome: "Dennis Ritchie",
                        sexo: 'M',
                        descricao: "Criou a linguagem de programação C."),
        ]
    }
}

Esse é o resultado esperado do teste acima utilizando a biblioteca Spock Report Extension.

Aqui está nosso intruso!

Mocking

Um Teste Unitário só pode ser chamado assim se for isolado do mundo externo, isto quer dizer, testa apenas aquela unidade de código mínima e mock as dependências. O Spock oferece meios bastante elegantes para isso.



import groovy.sql.Sql
import groovy.transform.EqualsAndHashCode
import spock.lang.Specification

class MockTest extends Specification {

    @EqualsAndHashCode
    class Carta {
        Integer id
        String nome
    }

    class MagicRepository {
        Sql sql

        MagicRepository() {
            sql = Sql.newInstance("jdbc:h2:mem:", "org.h2.Driver")
            sql.execute '''
              CREATE TABLE carta (
                id INTEGER PRIMARY KEY AUTO_INCREMENT, 
                nome VARCHAR(64)
              )'''
        }

        Carta addCarta(nome) {
            sql.execute "INSERT INTO carta(nome) VALUES ${nome}"
            findByNome(nome)
        }

        Carta findById(Integer id) {
            mapCarta sql.firstRow("select * from carta where id = ${id}")
        }

        Carta findByNome(String nome) {
            mapCarta sql.firstRow("select * from carta where nome = ${nome}")
        }

        private Carta mapCarta(retorno) {
            new Carta().tap {
                id = retorno.ID
                nome = retorno.NOME
            }
        }
    }

    class MagicService {
        MagicRepository repository

        Carta findById(Integer id) { repository.findById(id) }
    }

    def 'Stub permite apenas definir comportamento de métodos'() {
        given: 'Repository é apenas um stub'
        def carta = new Carta(nome: 'Mana Crypt')
        def stubRepository = Stub(MagicRepository) {
            findById(_ as Integer) >> { Integer id -> carta.tap { id: id } }
        }
        def service = new MagicService(repository: stubRepository)

        expect: 'O carta encontrada deve ser a carta do stub'
        service.findById(1) == carta.tap { id: 1 }
    }

    def "Spy permite saber quantas interações ocorreram e o retorno do método espiado"() {
        given:
        def esperada1 = new Carta(id: 1, nome: 'Black Lotus')
        def esperada2 = new Carta(id: 2, nome: 'Mana Crypt')

        def spyRepository = Spy(MagicRepository) {
            findById(2) >> esperada2
        }
        spyRepository.addCarta("Black Lotus")
        spyRepository.addCarta("Mox Pearl")

        def service = new MagicService(repository: spyRepository)

        when:
        def carta1 = service.findById(1)
        then:
        carta1 == esperada1
        spyRepository.findById(1) == esperada1
        1 * spyRepository.findById(1)

        when:
        def carta2 = service.findById(2)
        then:
        carta2 == esperada2
        spyRepository.findById(2) == esperada2
    }

    def "Mock pode tanto ver a quantidade de interações \
        quanto redefinir comportamento do método"() {
        given: 'Repositório será chamado três vezes'

        def esperada1 = new Carta(id: 1, nome: 'Mox Pearl')
        def esperada2 = new Carta(id: 2, nome: 'Mox Emerald')
        def mockRepository = Mock(MagicRepository) {
            2 * findById(1) >>> [esperada1, esperada2]
            1 * findById(2) >> esperada2
        }

        def service = new MagicService(repository: mockRepository)
        when:
        def carta1 = service.findById(1)
        def carta2 = service.findById(1)
        def carta3 = service.findById(2)
        then:
        carta1 == esperada1
        carta2 == esperada2
        carta3 == esperada2
    }
}

O Spock permite usar três categorias de mock:

Mock: Substitui o comportamento da classe quando ela é chamada e permite verificar como ela é usada. É o mais conhecido e tem foco em definir um “contrato” de como ele deve ser chamado, que deve responder e quantas vezes.
Spy: Não substitui o comportamento, mas permite verificar quando o método real da classe é chamado, o argumento e os resultados;
Stub: Apenas substitui comportamento, mas não permite verificar chamadas ao stub e nem testar esse acesso. É uma caixa preta que não pretende ser chamada, mas se for, retorna uma resposta padrão.

Para continuar estudando…

Código desse material: vai que a gente melhora algo.
Mocks aren’t stubs: Excelente texto do tio Bob
Spock and testing RESTful Api: Como ser um framework de testes sem teste de API RESTful?
Spock Report Extension: Uma extensão bastante útil para mostrar para o chefe.

Validação de regras: evitando blocos de ifs

Leandro Lima — Fri, 31 Jul 2020 19:29:33 +0000

O Problema 🤯

Lembro de trabalhar em um projeto em que eu tinha que validar vários dados que vinham de uma entrada de usuário e as validações eram regras de negócio complexas. Naquela época eu escrevi um método que possuía uma quantidade grande de if's.

Fiquei bastante contrariado com aquele código. Ele não era escalável, ele desobedecia à ideia de single responsability. Me sentia envergonhado com ele, mas não fui capaz de achar uma solução com o prazo apertado que tinha e ele foi ficando na minha cabeça sem solução.

Imagine que temos uma esteira onde um pacote de pão de queijo, como bom mineiro, adoro o ouro de Minas, é verificado quanto à sua qualidade e quantidade:

Quantidade de pães de queijo correta
Peso da embalagem
Volume de cada pão de queijo
Peso de cada pão de queijo

Nossa principal entidade é pão de queijo.

import lombok.Data;

public @Data class PaoDeQueijo {
    private double circumferencia;
    private double peso;

    public double getVolume() {
        return 4./3 * Math.PI * Math.pow(circumferencia/(2 * Math.PI), 3);
    }
}

Um pacote de pães de queijo nada mais é do que uma lista.

public final class PacotePaoQueijo extends ArrayList<PaoDeQueijo> {
}

Solução com vergonha 😞

public class VerificadorPacotePaoQueijoOld {

    public static final int QUANTIDADE_PAO_DE_QUEIJO_PACOTE = 10;
    public static final float PESO_PACOTE = 500f;
    public static final double MIN_VOLUME_PAO_DE_QUEIJO = 1.;
    public static final double MAX_PAO_DE_QUEIJO_VOLUME = 1.1;
    public static final double MIN_PESO_PAO_QUEIJO = 50;
    public static final double MAX_PESO_PAO_QUEIJO = 51;

    public boolean isPaoDeQueijoValido(PacotePaoQueijo pacote) throws PacoteDefeituosoException {
        final int quantidade = pacote.size();
        if(quantidade != QUANTIDADE_PAO_DE_QUEIJO_PACOTE)
            throw new PacoteDefeituosoException(String.format("Quantidade de pães de queijo errada. Esperava %d e " +
                            "encontrou %d.", QUANTIDADE_PAO_DE_QUEIJO_PACOTE, quantidade));

        final double pesoPacote = pacote.stream().map(PaoDeQueijo::getPeso).reduce(0., Double::sum);
        if (pesoPacote != PESO_PACOTE)
            throw new PacoteDefeituosoException(String.format("O peso do pacote de pães de queijo não está correto. " +
                            "Esperava %f g e encontrou %f g.",
                    PESO_PACOTE, pesoPacote));

        for (PaoDeQueijo paoDeQueijo : pacote) {
            try {
                validarPaoDeQueijo(paoDeQueijo);
            } catch (PaoDeQueijoDefeituosoException e) {
                throw new PacoteDefeituosoException("Esse pacote possui pães de queijo defeituosos.", e);
            }
        }

        return true;
    }

    public void validarPaoDeQueijo(final PaoDeQueijo paoDeQueijo) throws PaoDeQueijoDefeituosoException {
        final double peso = paoDeQueijo.getPeso();
        if(peso < MIN_PESO_PAO_QUEIJO || peso > MAX_PESO_PAO_QUEIJO)
            throw new PaoDeQueijoDefeituosoException(String.format("O pão de queijo encontra-se fora da faixa de peso permitida." +
                    "Esperava entre %f g e %f g e encontrou %f g.", MIN_PESO_PAO_QUEIJO, MAX_PESO_PAO_QUEIJO, peso));


        final double volume = paoDeQueijo.getVolume();
        if(volume < MIN_VOLUME_PAO_DE_QUEIJO || volume > MAX_PAO_DE_QUEIJO_VOLUME)
            throw new PaoDeQueijoDefeituosoException(String.format("Pão de queijo com volume errado. Esperava valores entre " +
                    "%f e %f e encontrou %f", MIN_VOLUME_PAO_DE_QUEIJO, MAX_PAO_DE_QUEIJO_VOLUME, volume));
    }
}

Nessa solução até separamos os métodos para verificar pacote e pão de queijo, usamos exceções adequadas, mas perceba, tratamos dois tipos de dados diferentes e temos inúmeros if's. O que aconteceria se você precisasse adicionar mais validações? Poderíamos validar temperatura, quantidade de queijo, sal, etc. Essa classe iria crescer e ficar monstruosa. Mesmo que separássemos a parte de regras para pão de queijo em uma nova classe ainda sim, seria ruim.

Imagine quanto é chato testar esse código, um método que valida tanta coisa geraria testes com várias validações. Fica claro que o single responsability principle não é respeitado.

A solução do livramento 🙌

@Log4j
public class EsteiraAvaliacaoPaesDeQueijo {
    private final List<Regra<PaoDeQueijo, PaoDeQueijoDefeituosoException>> regrasPaoDeQueijo =
            Arrays.asList(new RegraVolumePaoQueijo(), new RegraPesoPaoQueijo());
    private final List<Regra<PacotePaoQueijo, PacoteDefeituosoException>> regrasPacotePaoQueijo =
            Arrays.asList(new RegraQuantidadePaesPacote(), new RegraPesoPacote());


    public void validarPacote(PacotePaoQueijo pacote) {
        for (var regra : regrasPacotePaoQueijo) {
            try {
                regra.validar(pacote);
            } catch (PacoteDefeituosoException e) {
                log.error("Defeito no pacote.", e);
            }
        }

        for (PaoDeQueijo paoDeQueijo : pacote) {
            for (var regra : regrasPaoDeQueijo) {
                try {
                    regra.validar(paoDeQueijo);
                } catch (PaoDeQueijoDefeituosoException e) {
                    log.error("Defeito no pão de queijo.", e);
                }
            }
        }
    }
}

Nossas regras implementam uma interface única, mas poderia haver regras para pacote e regras para pão de queijo separadas.

public interface Regra<T, E extends Exception> {
    void validar(T produto) throws E;
}

Vamos ver aqui uma das regras, para verificação de peso do pacote.

public class RegraPesoPacote implements Regra<PacotePaoQueijo, PacoteDefeituosoException> {
    public static final float PESO_PACOTE = 500f;

    @Override
    public void validar(PacotePaoQueijo pacote) throws PacoteDefeituosoException {
        final double pesoPacote = pacote.stream().map(PaoDeQueijo::getPeso).reduce(0., Double::sum);
        if (pesoPacote == PESO_PACOTE)
            return;

        throw new PacoteDefeituosoException(String.format("O peso do pacote de pães de queijo não está correto. " +
                "Esperava %f g e encontrou %f g.", PESO_PACOTE, pesoPacote));
    }
}

Todas as regras seguem esse estilo, uma classe simples, com o método validar que lança uma exceção caso ela não seja validada.
Observe como fica auto-contido todo o universo da regra!

Plus com injeção Spring

Eu não testei essa funcionalidade com outros injetores de dependências, mas sei que com o Spring funciona bem.

O Spring consegue de forma simples injetar uma lista com todas as classes que implementam uma interface. Assim, nossa esteira fica ainda mais simples.

@AllArgsConstructor
@Component
@Log4j
public class EsteiraAvaliacaoPaesDeQueijo {
    private final List<Regra<PaoDeQueijo, PaoDeQueijoDefeituosoException>> regrasPaoDeQueijo;
    private final List<Regra<PacotePaoQueijo, PacoteDefeituosoException>> regrasPacotePaoQueijo;

    public void validarPacote(PacotePaoQueijo pacote) {
        for (var regra : regrasPacotePaoQueijo) {
            try {
                regra.validar(pacote);
            } catch (PacoteDefeituosoException e) {
                log.error("Defeito no pacote.", e);
            }
        }

        for (PaoDeQueijo paoDeQueijo : pacote) {
            for (var regra : regrasPaoDeQueijo) {
                try {
                    regra.validar(paoDeQueijo);
                } catch (PaoDeQueijoDefeituosoException e) {
                    log.error("Defeito no pão de queijo.", e);
                }
            }
        }
    }
}

Importante observação, não fique tentado a achar que se trata de um Chain of Responsabilities. Esse padrão prevê que uma responsabilidade está ligada à outra e compõem uma ordem definida. Já este não acopla as regras e, desta forma, se torna muito mais escalável. Outro ponto é que podemos criar regras que são reaproveitáveis, bastando que os objetos a validar possuam uma interface em comum.

O código desse projeto pode ser encontrado aqui.

Builder seguro e elegante

Leandro Lima — Fri, 24 Jul 2020 20:59:58 +0000

Builder é um dos padrões de projeto da classe dos criacionais da bíblia da Gangue dos Quadro. Esse padrão permite construir objetos complexos passo a passo e um efeito colateral disso é uma construção fluente para os objetos.

var pessoa = Pessoa.builder().nome("João").sobrenome("das Couve").idade(36).build();

Dessa forma, o que observamos do uso de builder e sua popularização está muito mais ligado à substituição de um construtor com muitos parâmetros por um design mais fluente do que propriamente o a intenção da GoF:

"...separação da construção de um objeto complexo da sua representação, de forma que o mesmo processo de construção possa criar diferentes representações."

Para diferenciar essa inteção do builder padrão, é comum chama-lo de Fluent Interface Builder.

O pattern está disponível nas IDEs para ser auto criado e ficou ainda mais conhecido no mundo Java através do Projeto Lombok que tirou um grande boilerplate e transformou em uma simples anotação.

Esse builder costuma ter o seguinte padrão:

package builder;

public class Pessoa {
    private final String nome;
    private final String sobrenome;
    private final int idade;

    public Pessoa(String nome, String sobrenome, int idade) {
        this.nome = nome;
        this.sobrenome = sobrenome;
        this.idade = idade;
    }

    public static PessoaBuilder builder() { return new PessoaBuilder(); }

    // Getters and setters

    public static class PessoaBuilder {
        private String nome;
        private String sobrenome;
        private int idade;

        public PessoaBuilder nome(String nome) {
            this.nome = nome;
            return this;
        }

        public PessoaBuilder sobrenome(String sobrenome) {
            this.sobrenome = sobrenome;
            return this;
        }

        public PessoaBuilder idade(int idade) {
            this.idade = idade;
            return this;
        }

        public Pessoa build() { return new Pessoa(nome, sobrenome, idade); }
    }
}

Mas sempre me incomodou que o builder, possuindo muitos passos, poderia contribuir para que o desenvolvedor desatento chame o build() prematuramente, isto é, com o objeto ainda incompleto. Isso só seria percebido em tempo de execução com uma exceção, ou pior, com a tentativa frustrada de acesso àquela propriedade esquecida.

Quando temos um construtor podemos impor que certos campos sejam final e isso obriga o desenvolvedor a preencher aqueles parâmetros, mas com o builder padrão, isso não é possível.

Esse incômodo, felizmente, acabou quando achei o artigo brilhante Simple Implementation of Fluent Builder - Safe Alternative To Traditional Builder do Sergiy Yevtushenko.

Esse gênio resolveu o problema e ainda de uma forma extremamente elegante!

package builder;

public class Pessoa {
    private final String nome;
    private final String sobrenome;
    private final int idade;

    public Pessoa(String nome, String sobrenome, int idade) {
        this.nome = nome;
        this.sobrenome = sobrenome;
        this.idade = idade;
    }

    public static PessoaBuilder.Stage0 builder() {
        return nome -> sobrenome -> idade -> () -> new Pessoa(nome, sobrenome, idade);
    }

    private interface PessoaBuilder {
        interface Stage0 { Stage1 nome(String nome); }
        interface Stage1 { Stage2 sobrenome(String sobrenome); }
        interface Stage2 { Stage3 idade(int idade); }
        interface Stage3 { Pessoa build(); }
    }
}

Aqui, definimos, de forma obrigatória, os parâmetros e a ordem em que eles devem ser preenchidos. Nosso builder é construído com passos representados por interfaces funcionais. Por conveniência, inseri esses passos dentro de uma interface que se comporta aqui como um namespace.

O método builder retorna o primeiro estágio, uma classe que tem apena o método nome;
Este retorna uma classe que tem também um único método que, sobrenome;
Sobrenome retorna a Stage3 com o método build(),
O build cria um objeto Pessoa.

Conclusão

O builder padrão é excelente quando se deseja dar ao desenvolvedor a flexibilidade de preencher os parâmetros que achar necessário, mantendo valores padrões para aqueles que não preencher. Para uma situação em que certos parâmetros não são opcionais, a solução apresentada é uma alternativa bastante enxuta e elegante.

Forem: Leandro Lima

Demystifying CPF and CNPJ Check Digit Algorithms: A Clear and Concise Approach

The collision problem

The cognitive load

Conclusion

[Code Compare] 2. Collections.singletonList vs List.of

Collections::singletonList

Method signature

Description

List::of

Method signature

Description

Conclusion

[Code Compare] 1. ArrayList vs Collections.singletonList

Array List

Collection::singletonList

Method signature:

Description

Conclusion

LocalStack: O poder da AWS direto da sua máquina

O que você vai ver nesse artigo

O que vamos fazer

Definição da nossa POC (Proof of Concept)

Repositório

TL;DR

Preparando o ambiente:

Rodando a aplicação:

Matando a aplicação:

Versão estendida: tudo o que você precisa para criar a sua própria POC

Configurando o ambiente

Docker

Docker Compose

Python

AWS CLI

LocalStack

Terraform

NodeJs

AWS Cloud

LocalStack

Terraform

API

Lambdas

Fila SQS

DynamoDB

Código

Rodando nossa aplicação

Conclusão

Crie testes unitários mais amigáveis e mais rapidamente com Spock

Dependências

Fields

Fixture Methods

Feature Methods

Condições

Explícitas ou implícitas

Exceções

Help Methods

Usando o método with para verificar campos

Mocking

Para continuar estudando…

Validação de regras: evitando blocos de ifs

O Problema 🤯

Solução com vergonha 😞

A solução do livramento 🙌

Plus com injeção Spring

Builder seguro e elegante

Conclusão

Referências

Usando o método `with` para verificar campos