Forem: Vitor Buxbaum Orlandi

Entendendo @decorators no Python em 6 passos

Vitor Buxbaum Orlandi — Tue, 14 Nov 2023 21:58:02 +0000

Decorators: um resumo

Quando falamos de decorators no Python, nos referimos à seguinte sintaxe:

@meu_decorator
def minha_funcao(param):
    ...

Ou seja: eu tenho uma função (mas poderia ser um método ou uma classe) chamada minha_funcao que está 'decorada' pelo decorator meu_decorator.

É comum ver essa sintaxe em diversas bibliotecas, como Flask e FastAPI (ao criar rotas), Pytest (ao criar fixtures), Dataclass (para definir uma dataclass) etc. Mas também há decorators "nativos", como @classmethod e @staticmethod.

Esse artigo é para você que já usou decorators em algum cenário, mas não sabe como poderia criar um por conta própria.

Entender a estrutura de um decorator pode ser uma tarefa complexa, mas irei dividir em passos mais simples de entender. Vou começar pegando leve e depois pode ficar mais pesado, mas você consegue! Vamos lá? 💜

Passo-a-passo

Passo 0: Crie uma função, e execute-a

Bem simples né? Vou adicionar alguns prints especiais que vão facilitar o entendimento do fluxo 😉

def my_function(my_param):
    print(f">> Iniciando my_function({my_param})")
    print(f">> Finalizando my_function({my_param})")


print("[Começando tudo]")
my_function("meu querido parâmetro")

Passo 1: atribuir a função a outro nome/variável

Caso você não saiba, funções também são objetos no Python! Elas possuem tipo (<class 'function'>) e atributos, e podemos "guardá-las" em outras variáveis.

Para esse passo, ficamos assim:

def my_function(my_param):
    print(f">> Iniciando my_function({my_param})")
    print(f">> Finalizando my_function({my_param})")


print("[Começando tudo]")
other_name = my_function  # Passo 1
print("[Troca de nome realizada]")  # Passo 1
other_name("meu querido parâmetro")  # Passo 1

Ou seja: other_name guarda my_function, então se eu chamar other_name na verdade estarei executando my_function.

Passo 2: criar uma função que retorna outra

Como funções são objetos, eu posso usar uma função para retornar outra:

def my_function(my_param):
    print(f">> Iniciando my_function({my_param})")
    print(f">> Finalizando my_function({my_param})")

# Passo 2
def get_function():
    print("> Iniciando get_function()")
    print("> Finalizando get_function()")
    return my_function


print("[Começando tudo]")
other_name = get_function()  # Passo 2
print("[Troca de nome realizada]")
other_name("meu querido parâmetro")

Repare que get_function não retorna o resultado de my_function, mas a função my_function em si.

Executando o código que temos até agora, a saída será:

[Começando tudo]
> Iniciando get_function()
> Finalizando get_function()
[Troca de nome realizada]
>> Iniciando my_function(meu querido parâmetro)
>> Finalizando my_function(meu querido parâmetro)

Passo 3: declarar uma função dentro da outra (função "mãe")

Aqui é uma refatoração relativamente simples, mas é essencial para garantirmos o comportamento do decorator: vamos deslocar a declaração de my_function para dentro de get_function.

def get_function():
    print("> Iniciando get_function()")    

    def my_function(my_param):  # Passo 3
        print(f">> Iniciando my_function({my_param})")  # Passo 3
        print(f">> Finalizando my_function({my_param})")  # Passo 3

    print("> Finalizando get_function()")
    return my_function


print("[Começando tudo]")
other_name = get_function()
print("[Troca de nome realizada]")
other_name("meu querido parâmetro")

Em termos de comportamento, nada vai mudar e a saída no terminal continuará a mesma. A diferença é que agora

não é mais possível acessar my_function diretamente pelo escopo global
my_function compartilha do escopo de get_function (como veremos a seguir)

Passo 4: Compartilhar parâmetro da "mãe" com execução da "filha"

Se seus neurônios ainda não tinham fritado, provavelmente chegou a sua hora 😅

Eis o que vamos fazer:

renomear get_function para mother_function (só pra facilitar as coisas)
adicionar um parâmetro em mother_function chamado mother_param
fazer my_function acessar mother_param (ilustrando com um print)

def mother_function(mother_param):  # Passo 4
    print(f"> Iniciando mother_function({mother_param})")  # Passo 4

    def my_function(my_param):
        print(f">> Iniciando my_function({my_param})")
        print(f">> Tenho acesso a ({mother_param})!")  # Passo 4
        print(f">> Finalizando my_function({my_param})")

    print(f"> Finalizando mother_function({mother_param})")  # Passo 4
    return my_function


print("[Começando tudo]")
other_name = mother_function("parâmetro materno")  # Passo 4
print("[Troca de nome realizada]")
other_name("meu querido parâmetro")

Ou seja: my_function consegue acessar variáveis no escopo de mother_function! Incrível, né??

Executando o código que temos até agora, a saída será:

[Começando tudo]
> Iniciando mother_function(parâmetro materno)
> Finalizando mother_function(parâmetro materno)
[Troca de nome realizada]
>> Iniciando my_function(meu querido parâmetro)
>> Tenho acesso a (parâmetro materno)!
>> Finalizando my_function(meu querido parâmetro)

Passo 5: passar uma nova função como parâmetro para a "mãe"

Agora vem o "pulo-do-gato": vamos tirar proveito do fato que funções são objetos, e passar uma função (ao invés de uma simples string) como parâmetro para mother_function. Dentro de my_function então poderei chamar essa nova função, manipulando (decorando 👀) como eu desejar.

Então agora vou:

criar uma nova função final_function e passá-la como mother_param
fazer my_function chamar mother_param (que será final_function) passando my_param como parâmetro
e por fim, exibir o retorno da chamada de other_function

def mother_function(mother_param):
    print(f"> Iniciando mother_function({mother_param})")

    def my_function(my_param):
        print(f">> Iniciando my_function({my_param})")
        res = mother_param(my_param)  # Passo 5
        print(f">> Finalizando my_function({my_param})")
        return res  # Passo 5

    print(f"> Finalizando mother_function({mother_param})")
    return my_function


# Passo 5
def final_function(final_param):
    print(f">>> Executando final_function({final_param})")
    return "RESULTADO FINAL"


print("[Começando tudo]")
other_name = mother_function(final_function)
print("[Troca de nome realizada]")
print(other_name("meu querido parâmetro")). # Passo 5

Executando esse código, a saída fica assim:

[Começando tudo]
> Iniciando mother_function(<function 'final_function'>)
> Finalizando mother_function(<function 'final_function'>)
[Troca de nome realizada]
>> Iniciando my_function(meu querido parâmetro)
>>> Executando final_function(meu querido parâmetro)
>> Finalizando my_function(meu querido parâmetro)
RESULTADO FINAL

Antes de seguir para o último passo

Nesse momento já temos o comportamento "cru" do decorator: uma função está sendo decorada por outra. 💅

Podemos afirmar isso porque quando fazemos other_name = mother_function(final_function), estamos usando mother_function para decorar final_function! Podemos dizer que other_function é a versão decorada de final_function.

Nesse caso é uma decoração simples (prints informando que a execução está iniciando/finalizando), mas ao final mostrarei um exemplo mais aplicável 😉

Passo 6: simplificando para a sintaxe com `@`

Agora que temos nosso decorator funcionando, só precisamos usar a famosa sintaxe com @. Nosso código vai ficar assim:

def mother_function(mother_param):
    # Nada muda aqui, escondi apenas para ajudar na leitura ;)
    ...  


@mother_function  # Passo 6
def final_function(final_param):
    print(f">>> Executando final_function({final_param})")
    return "RESULTADO FINAL"


print("[Começando tudo]")
print(final_function("meu querido parâmetro"))  # Passo 6

Removi o print [Troca de nome realizada] porque esse passo é feito implicitamente. Antes usávamos other_name para chamar a função decorada, mas agora final_function já guarda a versão decorada da função.

Isso significa que uma chamada para final_function na verdade executará my_function, e teremos a seguinte saída:

Executando o novo código, a saída fica assim:

> Iniciando mother_function(<function 'final_function'>)
> Finalizando mother_function(<function 'final_function'>)
[Começando tudo]
>> Iniciando my_function(meu querido parâmetro)
>>> Executando final_function(meu querido parâmetro)
>> Finalizando my_function(meu querido parâmetro)
RESULTADO FINAL

Uma diferença interessante aqui: [Começando tudo] agora aparece depois do print de mother_function, já que ela foi processada antes (quando usamos @mother_function).

Um exemplo mais divertido (e útil)

Para finalizar, vamos ver mais um exemplo para garantir que ficou nítido?! 🤩

Vamos fazer um decorator chamado shhh para suprimir a saída padrão (os "prints") de uma função. Fica mais ou menos assim:

def shhh(func):
    def wrapper(*args, **kwargs):
        with open(os.devnull, "w") as student_output:
            with contextlib.redirect_stdout(student_output):
                return func(*args, **kwargs)
    return wrapper

@shhh
def say_goodbye_to(name):
    print(f"Goodbye, {name}!")

def say_hello_to(name):
    print(f"Hello, {name}!")

say_goodbye_to("Jair")
say_hello_to("Luiz")

Executando esse exemplo, a saída será somente:

Hello, Luiz!

E aí, como você pensa em explorar o poder dos decorators?

Testando testes no Python - Parte 3: Pytest dentro do Pytest

Vitor Buxbaum Orlandi — Fri, 13 Oct 2023 21:43:20 +0000

Pessoas geralmente começam engatinhando, depois andam, evoluem para corrida, e algumas fazem coisas mais estranhas, como Parkour.

Pessoas Devs geralmente começam codando, depois testam, evoluem para o TDD, e algumas fazem coisas mais estranhas, como testes de testes.

Boas vindas! 🤩 Esse é o 3º artigo de uma curta série, contando um pouco mais sobre "testes de testes". 🧪

Vou discutir as motivações, alternativas, e detalhar as formas que fazemos em projetos de Python na Trybe.

Retomando de onde paramos

No artigo anterior mostrei como foi construída a primeira solução para testes de mutações customizadas, utilizando uma fixture autouse parametrizada com as mutações.

Mas havia uma limitação: nesse modelo a pessoa estudante precisa construir todos os seus testes dentro de uma função específica. É suficiente se queremos exercitar a criação de bons asserts, mas limitante quando pensamos em fazer testes mais elaborados e melhor organizados.

Trocando de "função" para "módulo"

Logo de início, a ideia era que precisávamos parar de parametrizar uma função de testes (o que a fixture faz no exemplo do artigo anterior), e fazer a parametrização para um arquivo (módulo) inteiro. Ou seja, executar todo um arquivo de testes da pessoa estudante para cada mutação.

Assim a pessoa estudante poderia fazer, por exemplo, 5 funções de teste em um arquivo e, quando uma mutação for aplicada, pelo menos 1 das 5 funções de teste deve falhar. Se todos os testes passarem para uma das mutações, consideramos que ainda não foi atingida a qualidade que esperamos.

A missão era minha, e eu não fazia ideia de como implementar. 😅 Novamente entramos naquele ponto que não havia nada pronto ou óbvio para usarmos, e precisei partir para pesquisa e experimentação.

"Como rodar um arquivo de teste no Pytest?"

Essa provavelmente foi a primeira pesquisa que fiz no Google, esperando que surgisse alguma resposta para o que precisávamos. E não, obviamente não apareceu.

Ou será que apareceu? 👀

As respostas para essa pesquisa são de conteúdos para iniciantes, e elas citam comandos básicos da CLI do Pytest:

python -m pytest tests/test_file.py

E meu primeiro pensamento foi:

"Eu já sei disso! Me mostre algo que eu não sei! 😫"

E logo em seguida:

"Calma, realmente é bem simples solicitar ao Pytest a execução de um arquivo completo de testes. Se eu conseguir fazer isso dentro de uma execução do Pytest que já está em curso, consigo usar a parametrização! Será que é possível? 🤔"

Resposta: Sim, é possível! 🎉

O Pytest é um módulo do Python como qualquer outro. Temos o costume de acioná-lo pela CLI, mas essa é apenas uma interface para um código "chamável" do Python. Na própria documentação do Pytest há a indicação de como executá-lo sem a CLI:

import pytest

retcode = pytest.main()

Um retcode igual a 0 (zero) significa que os testes passaram, falharam caso contrário.

Executando o Pytest dentro do Pytest

Não parece uma ideia muito agradável, e até a documentação da ferramenta faz um alerta sobre isso:

[...] fazer multiplas chamadas a pytest.main() a partir do mesmo processo (para re-executar testes, por exemplo) não é recomendado.

Parece que escreveram isso especialmente pra mim! 😂 Mas sem ousadia nunca venceremos obstáculos, não é mesmo?

Brincadeiras a parte, seguimos entendendo que esse é um uso controlado e (até o momento) com complexidade moderada.

Ajustando o exemplo anterior

No exemplo do artigo anterior toda a configuração de mutações era feita nos arquivos tests/sorter_mutations.py (definição das mutações) e tests/conftest.py (parametrização e patch das mutações), mas este 2º não será mais necessário.

Como nosso objetivo é somente ter um PASSED 🟢 caso a chamada do pytest.main() falhe para todas as mutações, podemos abandonar a complexidade da fixture parametrizada com XFAILs e seguir com uma opção mais direta: uma função de teste parametrizada que fará a chamada ao pytest.main().

Isolando essa nova função de teste em um arquivo dedicado, teremos o seguinte:

Que traduzido para código, fica assim:

from unittest.mock import patch
from tests import sorter_mutations
import pytest

mutated_functions = [
    sorter_mutations.no_exception_mutation,
    sorter_mutations.slice_input_mutation,
]


@pytest.mark.parametrize("mutation", mutated_functions)
def test_mutations_for_test_module(mutation):
    with patch("tests.test_sorter.sort_this_by", mutation):
        retcode = pytest.main(["tests/test_sorter.py"])

    assert retcode != 0, "Mutação deveria falhar"

Dado que não melhoramos o último exemplo de "teste da pessoa estudante", ao executar python -m pytest teremos a saída semelhante a seguinte:

Os 2 PASSED 🟢 indicados na imagem são:

A própria função da pessoa estudante sem a mutação aplicada
O teste com a mutação slice_input_mutation, que falhou como esperado na chamada pytest.main(["tests/test_sorter.py"])

E, como imaginávamos, a chamada pytest.main com a mutação no_exception_mutation retornou 0 e por isso nosso assert acusou um problema: "Mutação deveria falhar" (mas não falhou).

Melhorando a solução

Particularmente fiquei muito orgulhoso com essa solução! 💜 Mas há melhorias importante antes de chegarmos na versão disponibilizada para as turmas.

Ocultar logs excessivos

Quando executamos o Pytest internamente, ele se comporta de fato como uma nova execução, gerando todos os logs como esperado. Em nosso exemplo o terminal ficou poluído com logs equivalentes a 3 rodadas do Pytest, e isso não é bom para a experiência, além de confundir a pessoa estudante.

O Pytest possui algumas opções para reduzir a verbosidade de logs, mas sentimos que seria melhor ocultar completamente a saída das chamadas internas. Com 4 linhas podemos fazer a saída de um comando ser redirecionada para a "lixeira" /dev/null:

+import contextlib
+import os
from unittest.mock import patch
from tests import sorter_mutations
import pytest

mutated_functions = [
    sorter_mutations.no_exception_mutation,
    sorter_mutations.slice_input_mutation,
]


@pytest.mark.parametrize("mutation", mutated_functions)
def test_mutations_for_test_module(mutation):
    with patch("tests.test_sorter.sort_this_by", mutation):
+        with open(os.devnull, "w") as student_output:
+            with contextlib.redirect_stdout(student_output):
                 retcode = pytest.main(["tests/test_sorter.py"])
    assert retcode != 0, "Mutação deveria falhar"

Mutações devem falhar `and` Original deve passar

Tivemos um desafio semelhante na solução anterior usando a fixture: além de garantir que as mutações devem falhar, devemos garantir que o teste "normal" ou "original" deve passar.

Aqui novamente a biblioteca pytest-dependency e o módulo inspect entram como grandes amigos! Coletamos todas as funções de teste no arquivo tests/test_sorter.py e as adicionamos como dependências para o novo teste test_mutations_for_test_module.

Uma função que coleta todos os nodeid's de testes funcionais para um arquivo pode ser escrita assim:

import inspect
from pathlib import Path


def get_test_functions_from(student_test_module):
    test_file_path = Path(student_test_module.__file__).relative_to(Path.cwd())
    return [
        test_file_path + "::" + member[0]
        for member in inspect.getmembers(student_test_module)
        if inspect.isfunction(member[1]) and member[0].startswith("test_")
    ]

Nodeid é o identificador de um teste no Pytest, exigido pela pytest-dependency. É o mesmo texto que aparece antes de PASSED ou FAILED quando executamos a CLI com -vv. Exemplo:

Obs: Se a pessoa estudante utilizar parametrização em seus testes, essa função de coleta de nodeid's não será suficiente para a pytest-dependency funcionar corretamente. Por isso alteramos nosso fork novamente, garantindo a interpretação correta das dependências.

Nosso `assert`, nossas regras

Já que foi necessário criar um assert para garantir que o teste falhou para uma mutação, podemos aproveitar para criar uma mensagem de erro bem específica e didática. Porque só informar "Mutação deveria falhar" se podemos chegar em algo como "Seus testes em '{arquivo}' deveriam falhar com a mutação '{mutação}' definida em '{arquivo de mutações}', mas passaram. Confira essa dica: {dica específica da mutação}"?

Poderíamos ter um map/dicionário para definir a dica de cada mutação, mas escolhemos uma forma mais "preguiçosa": a docstring da própria mutação. Um exemplo seria:

# ...

@pytest.mark.parametrize("mutation", mutated_functions)
def test_mutations_for_test_module(mutation):
    with patch("tests.test_sorter.sort_this_by", mutation):
        with open(os.devnull, "w") as student_output:
            with contextlib.redirect_stdout(student_output):
                retcode = pytest.main(["tests/test_sorter.py"])
    assert retcode != 0, (
        "Seus testes em 'tests/test_sorter.py' deveriam falhar com a mutação,"
        f" mas passaram. Confira essa dica: {mutation.__doc__}"
    )

Primeiro a bagunça, depois a arrumação

Ufa... Muito código (e nem mostrei tudo) mas chegamos lá! 🎉

E nesse momento vem a dor de olhar todo aquele código criativo, mas ainda bagunçado. Só de olhar o "resultado final" já quero fugir de manutenções futuras, ainda mais pensando em múltiplos projetos e múltiplas turmas.

Por isso, aquela boa e velha refatoração sempre cai bem. Criando uma classe e algumas funções para isolar responsabilidades, temos um resultado mais palatável:

from unittest.mock import patch

import pytest

# Aproveitei nosso fork da pytest-dependency para
# posicionar as funções de apoio
from pytest_dependency import (
    assert_fails_with_mutation,
    get_skip_markers,
    get_test_assessment_configs,
    run_pytest_quietly,
)

from src.sorter import sort_this_by
from tests import test_sorter, sorter_mutations

# TA_CFG será um objeto para guardar dados que queremos obter facilmente
TA_CFG = get_test_assessment_configs(
    target_asset=sort_this_by,
    mutations_module=sorter_mutations,
    student_test_module=test_sorter,
)

# Com essa configuração garantimos que só testaremos as mutações
# caso a pessoa estudante tenha feito testes que passam.
pytestmark = get_skip_markers(TA_CFG)


@pytest.mark.parametrize("mutation", TA_CFG.MUTATED_FUNCTIONS)
def test_mutations_for_test_module(mutation):
    with patch(TA_CFG.PATCH_TARGET, mutation):
        return_code = run_pytest_quietly([TA_CFG.STUDENT_TEST_FILE_PATH])

    assert_fails_with_mutation(mutation, return_code, TA_CFG)

Muitas alegrias, até que...

Esse formato funcionou muito bem para nossos projetos sobre POO, Raspagem de Dados, Algoritmos e Estruturas de Dados, Flask... até que começamos a ensinar Django. 😅

Django é um framework incrível, mas ele abstrai muitos detalhes de implementação. Isso acontece principalmente em relação a comunicação com o banco de dados, e é mais "agravante" quando testes acessam o banco.

Tentamos bastante até entender que não seria viável, com a solução descrita nesse artigo, testar testes que precisavam acessar o banco de dados de uma aplicação Django. Precisávamos voltar ao passo da pesquisa, com boas doses de ousadia, criatividade e paciência.

Vou ser sincero aqui: ainda não tenho a resposta final! Fizemos uma prova de conceito com hooks do Pytest que parece promissora, mas ainda não chegamos lá.

Por isso, o próximo artigo pode demorar um pouco a sair, mas já estou ansioso para esse momento!

Testing tests in Python - Part 1: reasons and alternatives

Vitor Buxbaum Orlandi — Fri, 13 Oct 2023 17:00:05 +0000

People usually start by crawling, then walk, progress to running, and some do stranger things, like Parkour.

Software Developers usually start by coding, then testing, progress to TDD, and some do stranger things, like testing tests.

Welcome! 🤩 This is the first article in a short series, providing more information about "tests of tests." 🧪

I will discuss the motivations, alternatives, and detail the ways we do it in Python projects at Trybe.

How I came to know "tests of tests"

Nice to meet you, I'm Bux! At the moment I'm writing this text, I am an Instruction Specialist (i.e., a teacher and content producer) at Trybe, a Brazilian technology school, where I have been working for nearly 3 years.

In our Web Development course, students work on projects in which we assess if they have learned the content. These projects have automated tests, and the student must implement the necessary code to pass the tests in order to "pass the exam".

For example: when teaching Flask, we can have a project that requires the implementation of a CRUD for songs, and we create tests that validate the requirements of this CRUD. If the student's implementation passes our tests, they are approved. ✅

But what happens when we teach students how to create automated tests? How do we evaluate if they have created adequate tests?

What are tests of tests

In summary, "tests of tests" are the code we write to answer the last question, which is: have software tests been created that meet the specified requirements?

This is a question that any team of developers (or quality analysts) deeply concerned with the quality of the developed test can come across. But in our team's case, the intention was to "just" assess if the class can create good software tests.

Imagine, for example, a student needing to create tests for a function that searches for books, based on a string in their title, in the database. This search may have more details, such as being case-insensitive, returning paginated content, etc. I need to have an (automated) way to ensure that the student has created tests for this function.

What would you do?

Before moving on in the reading, take a moment to reflect: how would you do this? 🤔

Alternatives

Test Coverage Tool

This is one of the simplest ways to validate whether a code section is being tested. Most modern languages have ways to check how many and which lines of the source code are being tested when running a test.

In Python, we can use the Pytest plugin called pytest-cov (which, under the hood, uses coverage.py). With a few parameters, we can find out which lines of a specific file are "uncovered" by a specific test.

I can then run the student's tests and approve them if they have 100% coverage! 🎉

🟢 Advantages: It is simple to build and maintain, and it can be applied to virtually any context. Furthermore, the tool provides direct and explicit feedback (essential in an educational context).

🔴 Disadvantages: Test coverage is not a foolproof metric of test quality, as we can achieve 100% coverage without making a single assert.

Mutation Testing Tool

🌟 Mutation tests work on a simple but brilliant idea:

Unit tests should pass with the correct implementation of that unit, and should fail with incorrect implementations of that unit.

Libraries like mutmut can do this for us: the tool generates mutations in the source code and runs the tests again. Mutations are made at the level of the Abstract Syntax Tree (AST), such as changing comparators (< to >=) or booleans (True to False).

A good test is one that fails for all mutations. If your test continues to pass for some of the mutations, it means that it can be improved by validating more use cases.

🟢 Advantages: We can have more confidence that good tests are being created by the student, not just that the function/unit is being executed.

🔴 Disadvantages: Mutation testing tools add complexity to the testing process, which can impact the learning experience (remember, we want to use them in didactic projects). Additionally, the mutations offered by these tools are limited, generic, and have no 'strategy,' which can lead to a slowdown in the process.

Customized Mutation Tests

The idea behind the previous alternative is, as I mentioned, brilliant! 🌟

Customized mutation (a concept I'm probably creating now, with the help of ChatGPT) uses the same idea but with a different implementation: instead of automatically generating various random mutations in a file, we choose exactly the mutations we want using test doubles.

Picture this scenario: we ask students to create tests for the following Queue class:

class Queue():
    def __init__(self):
        self.__data = []  

    def __len__(self):
        return len(self.__data)

    def enqueue(self, value):
        self.__data.append(value)

    def dequeue(self):
        try:
            return self.__data.pop(0)
        except IndexError:
            raise LookupError("Queue is empty")

What we will do, then, is to create "broken" versions of the Queue class (with strategic mutations) and run the tests again. If the tests are well-written, they should fail with the mutations.

A possible mutated class for this case is:

from src.queue import Queue

# Notice that I'm using inheritance to reuse the methods 
# of the original class and perform a mutation only 
# in the 'dequeue' method.
class WrongExceptionQueue(Queue):
    def dequeue(self):
        try:
            return self.__data.pop(0)
        except IndexError:
            raise ValueError("Queue is empty")

In other words, if the student didn't create a test that validates the type of exception thrown by the dequeue method, they will not be approved.

🟢 Advantages: We continue to have confidence that good tests are being created by the student, not just that the function/unit is being executed. Moreover, we have more freedom to create complex and strategic mutations for each requirement, and we don't have to run unnecessary mutations (which don't add to learning), saving time and computational resources. As a bonus, we can provide extremely customized feedback (essential in the learning process), such as: "Did you remember to validate which exception is raised in the dequeue method?"

🔴 Disadvantages: Effort is required to think and code the mutations, as they will not be generated automatically. Additionally, there is no library (or at least we didn't find it) that facilitates the configuration of this type of test.

If it doesn't exist, we can create it! 🚀

And that's what we did: we created the necessary code to apply customized mutations in the tests. 🤓

In the next article in this series, I will detail how the 1st version (we are already moving towards the 3rd) of our "tests of tests" with customized mutations works. Until then, I'd like to know: how would you implement this functionality?

See you soon! 👋

Testando testes no Python - Parte 2: fixtures parametrizadas

Vitor Buxbaum Orlandi — Mon, 09 Oct 2023 18:34:31 +0000

Pessoas geralmente começam engatinhando, depois andam, evoluem para corrida, e algumas fazem coisas mais estranhas, como Parkour.

Pessoas Devs geralmente começam codando, depois testam, evoluem para o TDD, e algumas fazem coisas mais estranhas, como testes de testes.

Boas vindas! 🤩 Esse é o 2º artigo de uma curta série, contando um pouco mais sobre "testes de testes". 🧪

Vou discutir as motivações, alternativas, e detalhar as formas que fazemos em projetos de Python na Trybe.

Retomando de onde paramos

No artigo anterior, contei sobre o motivo de fazermos testes de testes em projetos dos cursos da Trybe, e resumi 3 principais alternativas e seus respectivos prós e contras.

Para o nosso cenário entendemos que o ideal (considerando todas as variáveis e limitações) era termos o teste de mutações customizadas.

Então chegou hora da verdade: a ideia era bonita mas precisava funcionar. E aí é que entram as habilidades do Capi, que ficou responsável pela implementação.

Na época, Capi era a pessoa mais sênior do time e não havia ninguém melhor para ser o pai (ou 'py'?) da criação. Ele gentilmente me concedeu a honra de escrever sobre a solução, e ainda revisar antes da publicação. 💜

Então aqui vou explicar como a solução funciona mas, se você quer saber melhor como foi o processo criativo para chegar lá, já sabe quem procurar! 😉

Entenda o caso: testar ordenação por critérios

A primeira versão surgiu em um contexto que, durante um dos projetos da nossa formação, a pessoa estudante precisava implementar testes para uma função chamada sort_this_by que ordena uma lista de dicionários (dicts). Logo, precisávamos testar os testes de cada estudante contra mutações dessa função de ordenação.

Os dicionários possuíam o mesmo conjunto de 6 chaves (como o exemplo a seguir) mas o critério de ordenação poderia ser apenas 3 dessas chaves. Além disso: ao selecionar a chave "min_score" como critério, a ordenação deveria ser crescente (e decrescente caso contrário); e uma exceção específica era levantada caso o parâmetro criteria não fosse um dos 3 valores válidos.

{
    "name": "Python",
    "age": 34,  # ordenação descrescente
    "max_score": 100,  # ordenação descrescente
    "min_score": 80,  # ordenação crescente
    "hobby": "coding",
    "short_name": "py",
}

Os detalhes da função sort_this_by não vão fazer diferença na explicação, mas é importante entender que havia um pouco de complexidade e casos de testes a serem cobertos. Para termos um código funcional sem complicar demais, considere a seguinte implementação no arquivo src/sorter.py:

def sort_this_by(unordered_list, criteria):
    return sorted(unordered_list, key=lambda x: x[criteria])

E um possível teste implementado por uma pessoa estudante em tests/test_sorter.py:

from src.sorter import sort_this_by


def test_sort_this_by():
    elements = [
        {"name": "John", "age": 23},
        {"name": "Mary", "age": 19},
        {"name": "Jane", "age": 20},
    ]
    criteria = "age"
    expect = [
        {"name": "Mary", "age": 19},
        {"name": "Jane", "age": 20},
        {"name": "John", "age": 23},
    ]
    res = sort_this_by(elements, criteria)
    assert res == expect

Criando as mutações

Como precisamos executar os testes da pessoa estudante "trocando" a função sort_this_by por uma mutação, precisamos criar essas mutações. Posso criar quantas e quais mutações desejar, mas isso sempre vai depender da complexidade da função original. Se a função original possui 5 code-paths (ifs, raises, excepts, returns, etc), provavelmente terei aproximadamente 5 mutações.

Penso em algumas mutações que forçariam a pessoa a exercitar certas habilidades de testes, e crio elas em um arquivo dedicado a isso. Em muitos casos, inclusive aproveitamos a função original para não precisar reescrever a lógica completa:

from src.sorter import sort_this_by


def no_exception_mutation(elements, criteria):
    """Mutação que nunca levanta exceção"""
    try:
        return sort_this_by(elements, criteria)
    except Exception:
        return elements


def slice_input_mutation(elements, criteria):
    """Mutação que altera lista inicial"""
    return sort_this_by(elements[1:], criteria)


# def other_mutation(elements, criteria):
#     ...

Agora, preciso que o teste test_sort_this_by seja executado uma vez para cada uma dessas mutações.

Parametrizando o teste com uso de uma fixture

Fixtures são a forma que o Pytest oferece para evitarmos duplicação de código em nossos testes, principalmente pensando em setup e teardown de recursos. Além da documentação, essa live do @dunossauro também é uma ótima opção para aprofundar no tema 😉

O Pytest já oferece uma forma de executar uma mesma função de teste para múltiplos valores: o marcador parametrize.

Entretanto, utilizar o marcador em nosso caso não é boa alternativa por 2 motivos. O 1º deles é simples de explicar: seria necessário inserir o marcador no arquivo da pessoa estudante. Isso aumenta a chance de erros, além de expor detalhes da nossa implementação com a qual o cliente (estudante) não deveria se preocupar. O 2º motivo só fará sentido em breve, então vou me permitir adiar essa explicação. 😅

Felizmente o Pytest também nos permite criar fixtures parametrizadas, que vão ser uma "mão na roda" nesse caso. Se inserirmos essa fixture no conftest.py, e ainda marcá-la como autouse para que ela seja aplicada automaticamente para todos os testes em seu contexto, conseguimos o que não tínhamos com o marcador parametrize. Então vamos à implementação do nosso tests/conftest.py:

import pytest
from tests import sorter_mutations

mutated_functions = (
    sorter_mutations.no_exception_mutation,
    sorter_mutations.slice_input_mutation,
)


@pytest.fixture(autouse=True, params=mutated_functions)
def validate_mutations(request):
    print(f"\n>>> Parâmetro mutação: {request.param}", end=' ')

Executando os testes, teremos a seguinte saída:

Uhuuul! ✅ Tudo passou! 🌟 Mas espera... 🤔 Como são mutações, os testes deveriam falhar não é mesmo?

Na verdade, não estamos fazendo nada com as mutações além de um simples print. Precisamos alterar nossa fixture para que ela faça a "mágica" que precisamos.

A "mágica"

🪄 A "mágica" é um simples patch! Assim como, durante testes de aplicações, podemos fazer o patch de uma dependência, podemos fazer isso dentro do próprio teste. Genial, Capi! 💜

A alteração no tests/conftest.py então será:

import pytest
+from unittest.mock import patch
from tests import sorter_mutations

mutated_functions = (
    sorter_mutations.no_exception_mutation,
    sorter_mutations.slice_input_mutation,
)


@pytest.fixture(autouse=True, params=mutated_functions)
def validate_mutations(request):
-    print(f"\n>>> Parâmetro mutação: {request.param}", end=' ')
+    with patch("tests.test_sorter.sort_this_by", request.param):
+        yield

Se executamos o teste novamente, temos o seguinte resultado:

Ou seja: o teste da "pessoa estudante" foi resistente (falhou) em uma mutação, mas não na outra. Para que o teste possa ser considerado robusto, ambas as mutações deveriam causar FAIL ❌.

Ainda temos ajustes a fazer, mas aqui chegamos na nossa grande vitória: temos nosso próprio teste de mutações customizadas! 🎉

E agora posso retomar ao 2º motivo que faria o marcador parametrize ser ruim para nosso caso: já imaginou como seria encaixar a funcionalidade do patch lá dentro? 😬

Ajustes para tudo rodar bem

Como estamos falando de um teste que será usado para pontuar estudantes de forma automatizada, precisamos de 2 ajustes principais:

1️⃣ O teste da pessoa estudante precisa passar com a função original;
2️⃣ Devemos transformar o conjunto de todos FAIL ❌ das mutações em um PASS ✅, para controlar se a pessoa estudante deve receber a pontuação ou não.

O ponto 1️⃣ é resolvido adicionando a função sort_this_by aos parâmetros da fixture validate_mutations (que poderia mudar de nome):

import pytest
from unittest.mock import patch
+from src.sorter import sort_this_by
from tests import sorter_mutations

mutated_functions = (
    sorter_mutations.no_exception_mutation,
    sorter_mutations.slice_input_mutation,
+    sort_this_by
)


@pytest.fixture(autouse=True, params=mutated_functions)
def validate_mutations(request):
    with patch("tests.test_sorter.sort_this_by", request.param):
        yield

Para o item 2️⃣ usamos o marcador XFAIL 🟨 do Pytest junto com os poderes do plugin pytest-dependency: marcamos os testes das mutações como XFAIL 🟨 e como dependência para o teste da função original. Ou seja: o teste da função original só será executado se os testes de mutação falharem.

Mas aqui surgiu um empecilho: o plugin pytest-dependency não entende XFAIL 🟨 como um resultado de sucesso. Então foi necessário criar um Fork do repositório com a melhoria (Capi até abriu um PR, mas até hoje não foi revisado pelo time do pytest-dependency).

Para usar essa opção, basta adicionar a linha accept_xfail = true no arquivo de configurações do Pytest (pytest.ini ou pyproject.toml),

Assim, nosso tests/conftest.py fica semelhante ao seguinte:

import pytest
from unittest.mock import patch
from src.sorter import sort_this_by
from tests import sorter_mutations

mutated_functions = (
    pytest.param(
        sorter_mutations.no_exception_mutation,
        marks=[pytest.mark.xfail(strict=True), pytest.mark.dependency],
    ),
    pytest.param(
        sorter_mutations.slice_input_mutation,
        marks=[pytest.mark.xfail(strict=True), pytest.mark.dependency],
    ),
    pytest.param(
        sort_this_by,
        marks=pytest.mark.dependency(
            depends=[
                "test_sort_this_by[no_exception_mutation]",
                "test_sort_this_by[slice_input_mutation]",
            ]
        ),
    ),
)


@pytest.fixture(autouse=True, params=mutated_functions)
def validate_mutations(request):
    with patch("tests.test_sorter.sort_this_by", request.param):
        yield

Refatorando a solução final

Sim, eu sei. Muito complexo para ler, e ainda mais para dar manutenção. Imagine se eu quiser criar mais uma função de mutação! Ou até mesmo se quiser trocar o nome de uma mutação, ou da função original... E lembre-se que a intenção é usar isso em vários projetos diferentes.

Por isso investimos um pouco mais de energia em uma refatoração, extraindo toda a construção da mutated_functions para uma função que recebe apenas 3 parâmetros:

O módulo com todas as mutações;
A função original a ser testada;
A função de teste da pessoa estudante.

Não vale a pena detalhar essa nova função aqui porque estaria fugindo do foco, mas preciso dizer que o módulo inspect foi uma grande ajuda!

Próximos passos

Esse modelo de teste de teste funcionou bem por muito tempo, em diversos projetos! E além de funções, funciona muito bem para mutações de classes.

Mas de todas as limitações, uma precisava ser resolvida com mais urgência: não queremos limitar que estudantes façam todos os testes de uma função (e principalmente de uma classe) em apenas 1 função de teste.

Precisávamos de uma forma para dar essa autonomia para a pessoa estudante, estimulando-a a escrever testes mais organizados com as ferramentas que desejar. No próximo artigo vou te contar como fizemos isso, mas adoraria saber: como você abordaria esse novo problema?

Nos ~~vemos~~ lemos em breve! 👋

Testando testes no Python - Parte 1: motivos e alternativas

Vitor Buxbaum Orlandi — Wed, 27 Sep 2023 13:30:32 +0000

Pessoas geralmente começam engatinhando, depois andam, evoluem para corrida, e algumas fazem coisas mais estranhas, como Parkour.

Pessoas Devs geralmente começam codando, depois testam, evoluem para o TDD, e algumas fazem coisas mais estranhas, como testes de testes.

Boas vindas! 🤩 Esse é o primeiro artigo de uma curta série, contando um pouco mais sobre "testes de testes". 🧪

Vou discutir as motivações, alternativas, e detalhar as formas que fazemos em projetos de Python na Trybe.

Como conheci "testes de testes"

Muito prazer, eu sou o Bux! No momento em que escrevo esse texto, sou Especialista em Instrução (i.e., professor e produtor de conteúdo) na Trybe, uma escola de tecnologia brasileira, onde trabalho há quase 3 anos.

No nosso curso de Desenvolvimento Web, estudantes realizam projetos em que avaliamos se aprenderam o conteúdo. Nesses projetos temos testes automatizados, e a pessoa estudante deve implementar o código necessário para passar nos testes para conseguir a aprovação.

Por exemplo: ao ensinarmos Flask podemos ter um projeto que exige a implementação de um CRUD de músicas, e criamos testes que validam os requisitos desse CRUD. Se a implementação da pessoa estudante passar em nossos testes, ela está aprovada. ✅

Mas o que acontece quando ensinamos a pessoa a criar testes automatizados? Como vamos avaliar se ela criou testes adequados?

O que são os testes de testes

Em resumo, "teste de testes" é o código que fazemos para responder a última pergunta, ou seja: foram criados testes de software que atendem aos requisitos informados?

Essa é uma pergunta que pode ser reflexão de qualquer time de pessoas desenvolvedoras (ou analistas de qualidade) profundamente preocupadas com a qualidade do teste desenvolvido. Mas, no caso do nosso time, a intenção era "apenas" avaliar se a turma consegue criar bons testes de software.

Imagine que, por exemplo, a pessoa estudante precise criar testes para uma função que busca por livros no banco de dados a partir de uma string em seu título. Essa busca pode ter mais detalhes, como ser case-insensitive, retornar conteúdo paginado, etc. Eu preciso ter uma forma (automatizada) de garantir que a pessoa criou testes para essa função.

O que você faria?

Antes de avançar na leitura, pare para refletir um pouco: como você faria isso? 🤔

Algumas alternativas

Ferramenta de cobertura de testes

Essa é uma das formas mais simples para validar se um trecho de código está sendo testado. A maioria das linguagens modernas possuem formas de averiguar, quando rodamos um teste, quantas e quais linhas do código fonte estão sendo testadas.

No Python podemos usar o plugin do Pytest chamado pytest-cov (que por baixo dos panos utiliza a coverage.py). Com alguns parâmetros, podemos saber quais linhas de um arquivo específico estão "descobertas" por um teste específico.

Eu posso então executar os testes da pessoa estudante, e aprová-la caso tenha 100% de cobertura! 🎉

🟢 Vantagens: é simples de construir e dar manutenção, e podemos aplicar a praticamente qualquer contexto. Além disso, a ferramenta tem um feedback direto e explícito (essencial num contexto de educação)

🔴 Desvantagens: cobertura de testes não é uma métrica de qualidade de testes "infalível", já que podemos conseguir 100% de cobertura sem fazer um único assert.

Ferramenta de testes de mutação

🌟 Testes de mutação funcionam a partir de uma ideia simples mas brilhante:

Os testes de uma unidade devem passar com a implementação correta dessa unidade, e devem falhar com implementações incorretas dessa unidade

Bibliotecas como o mutmut podem fazer isso por nós: a ferramenta gera mutações ("sujeiras") no código fonte e roda os testes novamente. As mutações são realizadas a nível da AST (árvore sintática abstrata), como trocar comparadores (< por >=) ou booleanos (True por False).

Um bom teste é aquele que falha para todas as mutações. Se o seu teste continua passando para alguma das mutações, significa que ele pode melhorar validando mais casos de uso.

🟢 Vantagens: podemos ter mais confiança de que bons testes estão sendo feitos pela pessoa estudante, e não apenas que a função/unidade está sendo executada.

🔴 Desvantagens: ferramentas de mutação adicionam complexidade na execução do teste, o que pode impactar a experiência de aprendizado (lembre-se, queremos utilizar em projetos didáticos). Além disso, as mutações oferecidas por essas ferramentas são limitadas, genéricas e não possuem nenhuma 'estratégia', o que pode levar a uma lentidão no processo.

Testes de mutações customizadas

A ideia por trás da alternativa anterior é, como já disse, brilhante! 🌟

A mutação customizada (um conceito que provavelmente estou criando agora, com ajuda do ChatGPT) utiliza essa mesma ideia mas com uma implementação diferente: ao invés de gerarmos automaticamente diversas mutações aleatórias em um arquivo, escolhemos exatamente as mutações que desejamos com uso de dublês.

Imagine o seguinte cenário: pedimos para que estudantes criem testes para a seguinte classe Queue (Queue = Fila, uma estrutura de dados sequencial em que inserimos elementos no fim, e removemos do início):

class Queue():
    def __init__(self):
        self.__data = []  

    def __len__(self):
        return len(self.__data)

    def enqueue(self, value):
        self.__data.append(value)

    def dequeue(self):
        try:
            return self.__data.pop(0)
        except IndexError:
            raise LookupError("A fila está vazia")

O que faremos, então, é criar versões "quebradas" da classe Queue (com mutações estratégicas) e rodar os testes novamente. Se os testes estiverem bem escritos, eles devem falhar com as mutações.

Uma possível classe com mutação para esse caso é:

from src.queue import Queue

# Repare que estou usando herança para reaproveitar
# os métodos da classe original e realizar mutação 
# apenas no método 'dequeue'
class WrongExceptionQueue(Queue):
    def dequeue(self):
        try:
            return self.__data.pop(0)
        except IndexError:
            raise ValueError("A fila está vazia")

Ou seja: se a pessoa estudante não fez um teste que valida o tipo da exceção levantada pelo método dequeue, ela não será aprovada.

🟢 Vantagens: continuamos tendo confiança de que bons testes estão sendo feitos pela pessoa estudante, e não apenas que a função/unidade está sendo executada. Mas além disso, temos mais liberdade para criar mutações complexas e estratégicas para cada requisito, e não precisamos executar os testes com mutações desnecessárias (que não agregam ao aprendizado) poupando tempo e recursos computacionais. E como bônus, podemos dar feedbacks (essenciais no processo de aprendizado) extremamente customizados como, por exemplo: "Você lembrou de validar qual exceção é levantada no método dequeue?"

🔴 Desvantagens: é necessário esforço para pensar e codificar as mutações, já que não serão geradas automaticamente. E, além disso, não existe (ou pelo menos não conseguimos encontrar) uma biblioteca que facilite a configuração desse tipo de teste.

Se não existe, a gente cria! 🚀

E foi isso que fizemos: criamos o código necessário para aplicar as mutações customizadas nos testes. 🤓

No próximo artigo dessa série vou detalhar como funciona 1ª versão (já estamos caminhando para a 3ª) dos nossos "testes de testes" com mutações customizadas. Até lá, queria saber: como você implementaria essa funcionalidade?

Nos ~~vemos~~ lemos em breve! 👋

Python's "TypeError: unhashable type"

Vitor Buxbaum Orlandi — Tue, 14 Mar 2023 15:02:00 +0000

Have you ever encountered a message like TypeError: unhashable type: 'set', and couldn't figure out why exactly this exception was raised? Well, I'm here to help you!

When does it usually happen

In addition to other situations, Python will raise this exception as soon as you try to store something that can not be hashed (AKA unhashable) in a structure implemented as a HashMap. The most common Python types that are implemented as HashMaps are dict and set.

For dicts, the TypeError: unhashable exception is raised when one tries to place an unhashable object as a key of the dictionary.

For sets, the TypeError: unhashable exception is raised when one tries to add an unhashable object to the set.

What does it mean "can (not) be hashed"

In Python, we say that something can be hashed if it is possible to calculate it's hash with the built-in hash(obj) function. This function returns an integer for a given object, respecting the following rule:

Two objects that compare equal must also have the same hash value, but the reverse is not necessarily true.

In computer science hash functions are used in multiple contexts (like cryptography and compression), but for HashMaps (as set and dict) it is used to compute a kind of ID for each object. This ID is used to organize data in such a way that we can do fast insertions and lookups.

It means that for every key in a dict (and for every object in a set) Python runs the function hash(obj), and that is when it actually raises the TypeError: unhashable.

Hashable and unhashable types in Python

As a general rule, Python immutable objects are hashable and mutable objects are unhashable.

Actually, since what is really happening is a call to the object's __hash__(self) magic method, anything can be hashable in python (as long as we implement it)!

So, to summarize it all, let's see a custom class with a custom __hash__(self) method



# I'm using dataclass here to avoid coding 
# __init__ and __repr__ methods
from dataclasses import dataclass


@dataclass
class User:
    name: str
    email: str

    def __hash__(self):
        # Here we define how we should compute
        # the hash for a given User. In this example
        # we use the hash of the '__email' attribute
        return hash(self.email)

    def __eq__(self, other):
        # This method is necessary if you want to
        # guarantee that User objects with same
        # email will not duplicate in a set or
        # as a dict key, for example
        return self.email == other.email

main_account = User("Vitor Buxbaum", "vitor.buxbaum@gmail.com")
gmail_account = User("Vitor Buxbaum", "vitor.buxbaum@gmail.com")
work_account = User("Vitor Buxbaum", "vitor.buxbaum@betrybe.com")
my_accounts = {main_account, gmail_account, work_account}

# my_accounts =
# {
#     User(name='Vitor Buxbaum', email='vitor.buxbaum@gmail.com'),
#     User(name='Vitor Buxbaum', email='vitor.buxbaum@betrybe.com')
# }

Forem: Vitor Buxbaum Orlandi

Entendendo @decorators no Python em 6 passos

Decorators: um resumo

Passo-a-passo

Passo 0: Crie uma função, e execute-a

Passo 1: atribuir a função a outro nome/variável

Passo 2: criar uma função que retorna outra

Passo 3: declarar uma função dentro da outra (função "mãe")

Passo 4: Compartilhar parâmetro da "mãe" com execução da "filha"

Passo 5: passar uma nova função como parâmetro para a "mãe"

Antes de seguir para o último passo

Passo 6: simplificando para a sintaxe com @

Um exemplo mais divertido (e útil)

Testando testes no Python - Parte 3: Pytest dentro do Pytest

Retomando de onde paramos

Trocando de "função" para "módulo"

"Como rodar um arquivo de teste no Pytest?"

Executando o Pytest dentro do Pytest

Ajustando o exemplo anterior

Melhorando a solução

Ocultar logs excessivos

Mutações devem falhar and Original deve passar

Nosso assert, nossas regras

Primeiro a bagunça, depois a arrumação

Muitas alegrias, até que...

Testing tests in Python - Part 1: reasons and alternatives

How I came to know "tests of tests"

What are tests of tests

What would you do?

Alternatives

Test Coverage Tool

Mutation Testing Tool

Customized Mutation Tests

If it doesn't exist, we can create it! 🚀

Testando testes no Python - Parte 2: fixtures parametrizadas

Retomando de onde paramos

Entenda o caso: testar ordenação por critérios

Criando as mutações

Parametrizando o teste com uso de uma fixture

A "mágica"

Ajustes para tudo rodar bem

Refatorando a solução final

Próximos passos

Testando testes no Python - Parte 1: motivos e alternativas

Como conheci "testes de testes"

O que são os testes de testes

O que você faria?

Algumas alternativas

Ferramenta de cobertura de testes

Ferramenta de testes de mutação

Testes de mutações customizadas

Se não existe, a gente cria! 🚀

Python's "TypeError: unhashable type"

When does it usually happen

What does it mean "can (not) be hashed"

Hashable and unhashable types in Python

Passo 6: simplificando para a sintaxe com `@`

Mutações devem falhar `and` Original deve passar

Nosso `assert`, nossas regras