DEV Community: Gabriel Augusto Morato dos Santos

Architectural Tests - Standardize your project's architecture now!

Gabriel Augusto Morato dos Santos — Mon, 17 Oct 2022 12:43:16 +0000

Introduction

Many times when we start a project, the biggest difficulty we have is when organizing our packages, classes and definitions of which class can have access to a certain other class, after defeating this difficulty, our next challenge is to maintain this organization and document for future developers or even us, how we defined the architecture of our project, this is what you will see next!

Why Architectural Testing?

As mentioned before, in addition to organizing our project more and defining a convention, we managed to have documentation in a very friendly way, as seen below, we saw a rule informing where the classes annotated with Entity should reside:

@ArchTest
    static final ArchRule entities_must_reside_in_a_domain_package =
            classes().that().areAnnotatedWith(Entity.class).should().resideInAPackage("..domain..")
                    .as("Entities must reside in the domain package");

But how about we get our hands-on now? :)

What technologies will we use?

For this article in question, we will need to have the following technologies in our project:

Java 8+: Java Programming Language in version 8+
Maven: Dependency management tool in Java.
ArchUnit: Tool that will be used for the development of our architectural tests
Spring: Programming framework

I will not go into too much of all the technologies used because it is not our purpose of this article.

Setting up our project:

In order for us to use archunit in our project, we will need to add the following dependency:

<dependency>
    <groupId>com.tngtech.archunit</groupId>
    <artifactId>archunit-junit5</artifactId>
    <version>0.18.0</version>
    <scope>test</scope>
</dependency>

After that, we will create a single class called ArchitectureTest in our test package, which will have the following implementation at this first moment:


@AnalyzeClasses(
        packages = "YourPackage",
        importOptions = ImportOption.DoNotIncludeTests.class
)
public class ArchitectureTest {
}

Note: In the example above, an option was inserted so that the tests were not included in our validation, but if you want to define a pattern in the name of your tests too, feel free. :)

Now, let's get to what interests us! =D

Together, we will define a simple architecture in which we will have Controller classes that will only be able to call Service classes and that will only be able to call Repository classes, as seen in the drawing below:

After that, we will define how the name of each class will look and finally, what will be the package that it will reside in, that said, let's create our architecture? :)

Defining the name of our classes:

In the 1st step we will define what the name of our classes should be, since we are extremely creative people, we are going to use the name of each annotation at the end of our class, why has no one ever thought of this before? :D

    @ArchTest
    static ArchRule ClassesThatHaveControllerAnnotation_MustEndWithControllerName =
            classes()
                    .that().areAnnotatedWith(Controller.class)
                    .should().haveSimpleNameEndingWith("Controller")
            .as("Dear developer, all our classes that are annotated as Controller, must have the name finalized with Controller");

As seen above, the use of ArchUnit tests are very simple and very intuitive, within our test we are informing that every class that is annotated as Controller, must have the name finalized as *Controller * and in addition we leave a tip for the next developer who doesn't do it the way we planned, using ".as(....)", isn't that cool? :)

I forced an error, changing the name of our class to UserJohn, look how cool what happened:

After that, we just create the rules for our other classes, but that's for you to try :)

If you can't, don't worry, just open the project's GitHub :)

Defining the residence of our classes:

In the 2nd step we will define where each class will reside, the test will be very similar to the previous one, so let's go? :)

@ArchTest
    static ArchRule ClassesThatHaveControllerAnnotation_MustResideInTheControllerPackage =
            classes()
                    .that().areAnnotatedWith(Controller.class)
                    .should().resideInAPackage("..controller..")
                    .as("Dear developer, all our classes that are annotated as Controller, must reside in the *.controller package");

With the example above, we inform in ".resideInAPackage(...)", which will be the place where our class will actually reside.

Defining which class will call which class:

Finally, to conclude our challenge, we need to define which class will call the other one, so that in this way, we have control of which class will be able to know the other, for that we will follow the example below:


 @ArchTest
    static final ArchRule ClassesResidingInControllerPackageCannotKnowRepository =
            noClasses().that().resideInAPackage("..controller..")
                    .should().dependOnClassesThat().resideInAPackage("..repository..")
            .as("Repository classes cannot be together with Controller classes :(");

In the example above, we defined that no class that resides in the Controller package can depend on any class that resides in the Repository package, what a sad love story, isn't it? :D

Thanks guys =D

I thank all of you who read my article and who accompany me in the creation of my content :)

ArchUnit, has great documentation and helps me a lot in the projects I run in my day to day, what do you think about presenting this in your projects? :)

Linkedin: https://www.linkedin.com/in/gabriel-augusto-1b4914145/
GitHub: https://github.com/GabrielAugusto1996/apply-archunit

Mutation Tests - Ensure the quality of your code now

Gabriel Augusto Morato dos Santos — Fri, 14 Oct 2022 10:25:52 +0000

Hello World, welcome to my article related to mutation testing.

Special thanks:

Before we start, I would like to thank my friend Paulo Ricardo for the encouragement of writing this article and being able to share my vision of this tool with the rest of you.

What is Mutation Testing anyway?

Pitest makes a mutation in your project, it allows you to guarantee a real margin of coverage within your tests by making a “copy” of the project and inserting errors to see if your tests will fail after the mutation. When the test fails the mutant is killed. If any mutant survives this means you need to do more unit tests, the live mutants serve as input to create more tests.

Okay, but how does this help me with the quality of my code?

Due to the classic rush that developers need to get into to deliver a particular project, testing is done more in order to increase code coverage, but this is not correct, testing comes with the objective of providing more quality that you are delivering to a client or consumer and also documenting so that another developer can better understand your code, later on you will understand where I want to go :)

What technologies will we use?

For this article, we will need to have the following technologies in our project:

Java 8+: Java Programming Language in version 8+
Junit 5: Test development framework
Maven: Build automation tool
Pitest: Tool to perform mutant tests
Spring: programming framework

I will not go into too much into all the technologies used because it is not our purpose of this article.

Setting up our project:

In order for us to use pitest, we need to use Junit 4 or higher, but as mentioned earlier, we will use Junit5:

<dependency>
    <groupId>org.junit.platform</groupId>
    <artifactId>junit-platform-launcher</artifactId>
    <version>1.7.1</version>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.junit.jupiter</groupId>
    <artifactId>junit-jupiter-engine</artifactId>
    <version>5.7.1</version>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.junit.vintage</groupId>
    <artifactId>junit-vintage-engine</artifactId>
    <version>5.7.1</version>
    <scope>test</scope>
</dependency>

It will also be necessary for us to add the pitest plugin to our project, which is the main objective of our article:

            <plugin>
                <groupId>org.pitest</groupId>
                <artifactId>pitest-maven</artifactId>
                <version>1.4.11</version>
                <dependencies>
                    <dependency>
                        <groupId>org.pitest</groupId>
                        <artifactId>pitest-junit5-plugin</artifactId>
                        <version>0.8</version>
                    </dependency>
                </dependencies>
                <configuration>
                    <targetClasses>
                        <param>YourClassPackage.*</param>
                    </targetClasses>
                    <targetTests>
                        <param>YourTestPackage.*</param>
                    </targetTests>
                </configuration>
            </plugin>

Note: There are other settings that you can set in the plugin according to your preference, such as excluding a certain class or package that will not be tested:

<excludedClasses>
 <param>PackageOfYourClasses.*</param>
 <param>PackageOfYourClasses.IamAClass</param>
</excludedClasses>

I just hope you don't delete the entire project, ok? :D

Revealing the problems with testing for coverage only:

As mentioned earlier, due to some rush or even lack of knowledge, the developer usually does the test just for coverage or ends up forgetting to insert some important validation, so let's analyze the following scenario:

Inside our project we have a class called UserFactory
In our method we will receive as parameters a String(name) and an Integer(year)
After that we will make the instance of the User class and we will set the parameters received to their respective attributes
Soon after, we will return the user

public final class UserFactory {

    private UserFactory() {}

    public static User create(final String name, final Integer year) {
        final User user = new User();

        user.setName(name);
        user.setYear(year);

        return user;
    }
}

Okay, after we understood the purpose of our method, let's go to our test class, UserFactoryTest:

class UserFactoryTest {

    @Test
    @DisplayName("Should return a User - When success")
    void create_User_WhenSuccess() {
        final Integer year = 10;
        final String name = "Dudu";

        final User user = UserFactory.create(name, year);

        Assertions.assertNotNull(user);
        Assertions.assertEquals(name, user.getName());
    }
}

As we can see, we made the method call of our class and made the following checks:

We looked that the return object is not null
We verified that expected name* is equal to the name entered in user

Shall we check out our coverage?

But after all, in this simple example we had no problem, where was our mistake?

Exactly, we forgot to do the validation if the year attribute was set correctly, let's see what the Pitest has to say?

Getting more into the tool:

To run Pitest we can just execute following command:

mvn org.pitest:pitest-maven:mutationCoverage

Or run the plugin directly in your IDE by clicking on the pitest:mutationCoverage option, the choice is yours :)

If project is configured correctly, you will get the following results, when execution is complete:

As we can see above, the Pitest generated 5 mutations and with our test we managed to kill only 3, but don't worry, so that you have a more analytical view, the *Pitest * generates a report for you, so that we can access it, just follow the following path:

target
pit-reports
index.html

As we can see, Pitest took our line from user.setYear(year); and said that if we remove the call from that line, the result will be the same and we know this is not true, right? :)

So now we just go back to our test class and make the necessary changes.

Thank you guys:

Thanks to all of you for reading my article, as I said this was the first of many to come, so if you liked it or have a comment so you can be supporting and encouraging me I will be extremely grateful :)

Now I leave a special challenge for you to run Pitest on your project and tell me what was your reaction when you saw the result :D

Note: My first time was not very positive, but it helped me to have a higher quality in the projects :D

Linkedin: https://www.linkedin.com/in/gabriel-augusto-1b4914145/
GitHub: https://github.com/GabrielAugusto1996/apply-pitest

Testes Arquiteturais - Padronize já a arquitetura do seu projeto!

Gabriel Augusto Morato dos Santos — Tue, 20 Apr 2021 01:33:06 +0000

Introdução

Muita das vezes quando iniciamos um projeto, a maior dificuldade que possuímos é no momento de fazer a organização entre os nossos pacotes, classes e definições de qual classe poderá ter acesso a determinada outra classe, após derrotarmos essa dificuldade, o nosso próximo desafio é mantermos essa organização e documentarmos para os futuros desenvolvedores ou até mesmo nós, como definimos a arquitetura do nosso projeto, isso é o que você irá ver a seguir!

Por quê Testes Arquiteturais?

Como foi dito anteriormente, além de organizarmos mais o nosso projeto e definirmos uma convenção, conseguimos ter uma documentação de uma forma bem amigável,conforme exemplo visto abaixo, vimos uma regra informando onde as classes anotadas com Entity deverão residir:

@ArchTest
    static final ArchRule entities_must_reside_in_a_domain_package =
            classes().that().areAnnotatedWith(Entity.class).should().resideInAPackage("..domain..")
                    .as("Entidades deverão residir no pacote de domínios");

Mas que tal agora colocarmos a mão na massa? :)

Quais tecnologias iremos utilizar?

Para esse artigo em questão, iremos precisar ter as seguintes tecnologias no nosso projeto:

Java 8+: Linguagem de Programação Java na versão 8+
Maven: Ferramenta para o gerenciamento de dependências no Java.
ArchUnit: Ferramenta que será utilizada para o desenvolvimento dos nossos testes arquiteturais
Spring: Framework de programação

Não irei entrar muito adentro de todas as tecnologias utilizadas pois não é o nosso objetivo desse artigo.

Configurando o nosso projeto:

Para que possamos utilizar o archunit no nosso projeto, será necessário adicionarmos a seguinte dependência:

<dependency>
    <groupId>com.tngtech.archunit</groupId>
    <artifactId>archunit-junit5</artifactId>
    <version>0.18.0</version>
    <scope>test</scope>
</dependency>

Após isso, iremos fazer uma criação de uma única classe chamada ArchitectureTest no nosso pacote de testes, no qual irá ter a seguinte implementação nesse primeiro momento:


@AnalyzeClasses(
        packages = "SeuPacote",
        importOptions = ImportOption.DoNotIncludeTests.class
)
public class ArchitectureTest {
}

Observação: No exemplo acima, foi inserido uma opção para que não incluísse os testes na nossa validação, mas caso você queira definir um padrão no nome dos seus testes também, pode ficar à vontade. :)

Agora sim, vamos ao que nos interessa! =D

Juntos, iremos definir uma arquitetura simples na qual iremos ter classes de Controller que irão poder chamar apenas as classes Service e que poderão chamar somente classes Repository, conforme visto no desenho abaixo:

Após isso, iremos definir como irá ficar o nome de cada classe e por último, qual será o pacote que a mesma irá residir, dito isso, vamos criar a nossa arquitetura? :)

Definindo o nome das nossas classes:

No 1º passo iremos definir como deverá ser o nome das nossas classes, já que somos pessoas extremamente criativas, vamos utilizar o nome de cada anotação no final da nossa classe, porquê será que ninguém nunca pensou nisso antes? :D

    @ArchTest
    static ArchRule ClassesQuePossuemAnotacaoController_DeveraoFinalizarComNomeController =
            classes()
                    .that().areAnnotatedWith(Controller.class)
                    .should().haveSimpleNameEndingWith("Controller")
            .as("Caro desenvolvedor, todas as nossas classes que estão anotadas como Controller, deverão ter o nome finalizado com Controller");

Como visto acima, o uso dos testes do ArchUnit são bem simples e bastante intuitivos, dentro do nosso teste estamos informando que toda classe que está anotada como Controller, deverá ter o nome finalizado como Controller e além disso deixamos uma dica para o próximo desenvolvedor que não fizer da forma que nós planejamos, utilizando o ".as(....)", isso não é legal? :)

Forcei um erro, mudando o nome da nossa classe para UsuarioJoao, olha que legal o que aconteceu:

Após isso, basta criarmos as regras para as nossas outras classes, mas isso agora eu deixo para você tentar :)

Caso não consiga não se preocupe, basta abrir o GitHub do projeto :)

Definindo a residência das nossas classes:

No 2º passo iremos definir onde cada classe irá residir, o teste irá ser bastante similar ao anterior, então vamos lá? :)

@ArchTest
    static ArchRule ClassesQuePossuemAnotacaoController_DeveraoResidirNoPacoteController =
            classes()
                    .that().areAnnotatedWith(Controller.class)
                    .should().resideInAPackage("..controller..")
                    .as("Caro desenvolvedor, todas as nossas classes que estão anotadas como Controller, deverão residir no pacote *.controller");

Com o exemplo acima, informamos no ".resideInAPackage(...)", qual será o local que a nossa classe de fato irá residir.

Definindo qual classe irá chamar qual classe:

Por último, para concluirmos o nosso desafio, precisamos definir qual classe irá chamar a outra, para que dessa forma, tenhamos o controle de qual classe poderá conhecer a outra, para isso iremos seguir o exemplo abaixo:


 @ArchTest
    static final ArchRule ClassesQueResidemNoPacoteControllerNaoPodemConhecerRepository =
            noClasses().that().resideInAPackage("..controller..")
                    .should().dependOnClassesThat().resideInAPackage("..repository..")
            .as("As classes Repository não podem ficar juntas das classes Controller :(");

No exemplo acima, definimos que nenhuma classe que resida no pacote Controller poderá depender de nenhuma classe que resida no pacote Repository, que história triste de amor, não? :D

Obrigado pessoal =D

Agradeço a todos vocês que leram o meu artigo e que me acompanham na criação dos meus conteúdos :)

O ArchUnit, possui uma ótima documentação e me ajuda muito nos projetos que executo no meu dia à dia, o que você acha de apresentar isso nos seus projetos? :)

Linkedin: https://www.linkedin.com/in/gabriel-augusto-1b4914145/
GitHub: https://github.com/GabrielAugusto1996/aplicando-archunit

Testes de Mutação - Garanta já a qualidade do seu código

Gabriel Augusto Morato dos Santos — Wed, 17 Mar 2021 03:16:23 +0000

Hello World, sejam bem vindos ao meu artigo relacionado à testes de mutação.

Agradecimentos especiais:

Antes de iniciarmos, gostaria muito de agradecer ao meu amigo de trabalho Paulo Ricardo pelo incentivo de estar escrevendo esse artigo e poder compartilhar a minha visão dessa ferramenta com o restante de vocês.

Afinal, o que é o Teste de Mutação?

O Pitest faz uma mutação no seu projeto, ele permite que você garanta uma margem de cobertura real dentro dos seus testes fazendo uma “cópia” do projeto e inserindo erros para ver se o seus testes irão falhar após a mutação. Quando o teste falha o mutante é morto. Caso algum mutante sobreviva isso significa que você precisa fazer mais testes unitários, os mutantes vivos servem de input para criar mais testes.

Ok, mas como isso me ajuda com a qualidade do meu código?

Devido as clássicas correrias que os desenvolvedores precisam entrar para entregar um determinado projeto, acaba que o teste é feito mais para poder aumentar a cobertura do código, só que isso não é o correto, os testes vem com o objetivo de fornecer mais a qualidade do que você está entregando para algum cliente ou consumidor e também documentar para que outro desenvolvedor entenda melhor o seu código, mais pra frente vocês irão entender em que ponto quero chegar :)

Quais tecnologias iremos utilizar?

Para esse artigo em questão, iremos precisar ter as seguintes tecnologias no nosso projeto:

Java 8+: Linguagem de Programação Java na versão 8+
Junit 5: Framework para desenvolvimento de testes
Maven: Ferramenta de automação para compilação
Pitest: Ferramenta para realizar os testes mutantes
Spring: Framework de programação

Não irei entrar muito a dentro de todas as tecnologias utilizadas pois não é o nosso objetivo desse artigo.

Configurando o nosso projeto:

Para que possamos utilizaf o pitest, precisamos fazer o uso do Junit 4 ou superior, mas como foi dito anteriormente, iremos utilizar o Junit5:



<dependency>
    <groupId>org.junit.platform</groupId>
    <artifactId>junit-platform-launcher</artifactId>
    <version>1.7.1</version>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.junit.jupiter</groupId>
    <artifactId>junit-jupiter-engine</artifactId>
    <version>5.7.1</version>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.junit.vintage</groupId>
    <artifactId>junit-vintage-engine</artifactId>
    <version>5.7.1</version>
    <scope>test</scope>
</dependency>

Também será necessário que a gente adicione no nosso projeto o plugin do pitest que é o objetivo principal do nosso artigo:



            <plugin>
                <groupId>org.pitest</groupId>
                <artifactId>pitest-maven</artifactId>
                <version>1.4.11</version>
                <dependencies>
                    <dependency>
                        <groupId>org.pitest</groupId>
                        <artifactId>pitest-junit5-plugin</artifactId>
                        <version>0.8</version>
                    </dependency>
                </dependencies>
                <configuration>
                    <targetClasses>
                        <param>SeuPacoteDeClasse.*</param>
                    </targetClasses>
                    <targetTests>
                        <param>SeuPacoteDeTeste.*</param>
                    </targetTests>
                </configuration>
            </plugin>

Observação: Existem outras configurações que você pode inserir no plugin conforme a sua preferência, como por exemplo, excluir uma determinada classe ou pacote que não irá ser testado:



<excludedClasses>
 <param>PacoteDasSuasClasses.*</param>
 <param>PacoteDasSuasClasses.SouUmaClasse</param>
</excludedClasses>

Só espero que você não exclua o projeto inteiro, ok? :D

Revelando a falha de fazer teste apenas para cobertura:

Conforme foi dito anteriormente, devido à alguma correria ou até mesmo por falta de conhecimento, o desenvolvedor costuma fazer o teste apenas pela cobertura ou acaba esquecendo de inserir alguma validação importante, então vamos analisar o seguinte cenário:

Dentro do nosso projeto temos uma classe chamada UsuarioTranslator
No nosso método receberemos como parâmetros uma String(nome) e um Integer(idade)
Após isso iremos fazer a instância da classe Usuario e iremos settar os parâmetros recebidos em seus respectivos atributos
Logo em seguida, iremos retornar o usuario



public final class UsuarioTranslator {

    private UsuarioTranslator() {}

    public static Usuario of(final String nome, final Integer idade) {
        final Usuario usuario = new Usuario();

        usuario.setNome(nome);
        usuario.setIdade(idade);

        return usuario;
    }
}

Ok, após entendermos o objetivo do nosso método, vamos para a nossa classe de teste, UsuarioTranslatorTest:



class UsuarioTranslatorTest {

    @Test
    @DisplayName("Deverá retornar Usuario - Quando sucesso")
    void of_Usuario_QuandoSucesso() {
        final Integer idade = 10;
        final String nome = "Dudu";

        final Usuario usuario = UsuarioTranslator.of(nome, idade);

        Assertions.assertNotNull(usuario);
        Assertions.assertEquals(nome, usuario.getNome());
    }
}

Como podemos ver, fizemos a chamada do método da nossa classe e fizemos as seguintes verificações:

Verificamos que o objeto de retorno não está nulo
Verificamos que nome* esperado é igual ao nome informado no usuario

Vamos conferir a nossa cobertura?

Mas afinal, nesse exemplo simples não tivemos nenhum problema, onde estava o nosso erro?

Exatamente, esquecemos de fazer a validação se o atributo de idade foi settado corretamente, vamos ver o que o Pitest tem a dizer?

Entrando mais na ferramenta:

Para que possamos executar o Pitest basta executar o seguinte comando no terminal do seu projeto:



mvn org.pitest:pitest-maven:mutationCoverage

Ou executar o plugin diretamente na sua IDE clicando na opção pitest:mutationCoverage, a escolha é sua :)

Após fazer a execução e tiver configurado direitinho o seu projeto até aqui, você irá ter o seguinte resultado:

Como podemos ver acima, o Pitest fez a geração de 5 mutações e com o nosso teste conseguimos matar apenas 3, mas não se preocupe, para que você tenha uma visão mais analítica, o Pitest gera pra você um relatório, para que possamos acessar o mesmo basta seguir o seguinte caminho:

target
pit-reports
index.html

Como podemos ver, o Pitest tirou a nossa linha do usuario.setIdade(idade); e disse que se removermos a chamada dessa linha, o resultado será o mesmo e sabemos que isso não é verdade, correto? :)

Então agora basta voltarmos na nossa classe de teste e fazer as suas devidas alterações.

Obrigado pessoal:

Agradeço a todos vocês por terem lido o meu artigo, como foi dito esse foi o primeiro de muitos que virão, então caso tenham gostado ou tenha um comentário para que possa estar me apoiando e me incentivando ficarei extremamente grato :)

Agora deixo um desafio especial para que você execute o Pitest no seu projeto e diga qual foi a sua reação quando viu o resultado :D

Observação: Na minha primeira vez não foi muito positivo, mas me ajudou a ter uma qualidade maior nos projetos :D

Linkedin: https://www.linkedin.com/in/gabriel-augusto-1b4914145/
GitHub: https://github.com/GabrielAugusto1996/aplicando-pitest