Pacotes, diagramas de classes e testes unitários em Java

Um pacote agrupa classes e interfaces relacionadas sob um mesmo nome. Ele também separa nomes: duas classes chamadas Parcel podem coexistir quando seus nomes de pacote são diferentes. Um pacote oferece ao Java um limite de acesso, além de uma forma de organizar arquivos.

Declare o pacote primeiro

Um arquivo-fonte comum começa com sua declaração de pacote, seguida das importações e depois da classe. Comentários podem aparecer antes da declaração. Por exemplo:

package com.example.parcels.domain;

public class Parcel {
    private int weightGrams;

    public Parcel(int weightGrams) {
        this.weightGrams = weightGrams;
    }
}

Todo tipo de nível superior nesse arquivo pertence a com.example.parcels.domain. Um arquivo tem no máximo uma declaração de pacote. A classe pública Parcel deve ficar em Parcel.java; alterar apenas a pasta não altera o pacote declarado.

Transforme pontos em pastas

O diretório raiz do código-fonte é a pasta onde começa o caminho do pacote. Em um projeto Maven ou Gradle padrão, o código Java principal começa em src/main/java. Substitua cada ponto no nome do pacote por uma barra e depois acrescente o nome da classe:

src/main/java/
  com/example/parcels/domain/Parcel.java

O pacote é com.example.parcels.domain, não src.main.java.com.example.parcels.domain. As três primeiras pastas descrevem a estrutura da construção; elas não fazem parte do nome Java. Quando uma IDE informa uma incompatibilidade de pacote, compare a declaração com o caminho abaixo do diretório raiz do código-fonte. Mova o arquivo ou corrija a declaração para que correspondam.

Nomes de pacotes usam letras minúsculas. Organizações geralmente invertem seu domínio: example.com torna-se com.example, seguido do projeto e de sua área. Um projeto sem domínio pode usar parcels.domain. Se um componente do domínio invertido contiver um hífen, substitua-o por um sublinhado, como em org.example.hyphenated_name. Evite o espaço de nomes java e javax da plataforma.

Use o nome completo da classe

Um nome totalmente qualificado une o pacote e o nome simples da classe: com.example.parcels.domain.Parcel. Ele identifica a classe mesmo quando outro pacote também tem uma Parcel. O código pode nomear uma classe acessível por extenso sem importação:

java.util.ArrayList<String> names = new java.util.ArrayList<>();

Para executar uma classe principal em um pacote, forneça seu nome completo e um caminho de classes apontando para a raiz da árvore de pacotes compilada. Na pasta do projeto:

javac -d out src/main/java/com/example/parcels/Main.java src/main/java/com/example/parcels/domain/Parcel.java
java -cp out com.example.parcels.Main

Aqui, javac -d out cria a árvore de saída, e java -cp out busca a partir da raiz dessa árvore. Iniciar java Main de uma pasta de pacote perde a parte do pacote na identidade da classe. Ferramentas de construção e IDEs normalmente gerenciam esses comandos.

Distinga pacotes próximos

com.example.parcels e com.example.parcels.domain são pacotes separados. Compartilhar um prefixo de nome não concede direitos de acesso adicionais. Um arquivo sem declaração pertence ao pacote sem nome. Pacotes nomeados não podem importar suas classes, portanto use pacotes nomeados em todo programa com várias partes.

Uma importação permite que um arquivo-fonte use o nome simples de um tipo acessível. Ela informa ao compilador o significado do nome. Não copia a classe, não baixa uma biblioteca nem torna pública uma classe oculta.

Leia o início de um arquivo-fonte

A interface do usuário pertence a um pacote e usa classes de outros dois:

package com.example.parcels.ui;

import com.example.parcels.domain.Parcel;
import com.example.parcels.domain.ShippingCalculator;
import java.util.Scanner;

public class TextUI {
    private Scanner scanner;
    private ShippingCalculator calculator;
}

Parcel e ShippingCalculator vêm do pacote de domínio do programa; Scanner vem da biblioteca Java. Cada importação se aplica apenas a esse arquivo. Outro arquivo que usa Scanner precisa de sua própria importação ou do nome completo java.util.Scanner.

Escolha um tipo único ou um curinga

import java.util.Scanner; é uma importação de tipo único. Sua classe exata fica visível para quem lê. import java.util.*; é uma importação sob demanda: tipos acessíveis nesse pacote podem ser nomeados quando usados. O curinga não carrega classes não utilizadas no programa nem o torna mais lento.

O curinga se limita àquele pacote. Ele não inclui java.util.function.Function nem java.util.stream.Collectors, que estão em pacotes separados. A mesma regra se aplica ao seu próprio código: import com.example.parcels.*; não alcança com.example.parcels.domain.Parcel.

Três casos não precisam de importação: tipos no mesmo pacote, tipos disponíveis automaticamente em java.lang e tipos nomeados por extenso. Por isso, String, System, Math, Integer e Object aparecem frequentemente sem importações.

Resolva um nome simples compartilhado

Tanto java.util quanto java.awt têm uma classe chamada List. Duas importações de tipo único para essas classes diferentes causam erro de compilação. Duas importações com curinga podem coexistir, mas o nome simples List torna-se ambíguo quando usado. Uma importação de tipo único tem precedência sobre uma importação com curinga.

Se ambas as classes forem necessárias, importe uma e escreva a outra por extenso:

import java.util.List;

class NameDisplay {
    private List<String> names;
    private java.awt.List widget;
}

As importações Java não oferecem uma sintaxe de apelido como import ... as .... O nome totalmente qualificado é a maneira de distinguir o segundo tipo.

Importe um membro estático

Uma importação estática dispensa o nome da classe proprietária na chamada de um membro estático:

import static java.lang.Math.sqrt;

O arquivo agora pode chamar sqrt(16.0). O código de teste frequentemente usa import static org.junit.jupiter.api.Assertions.assertEquals; para que as asserções sejam lidas como verificações diretas. No código comum do programa, use importações estáticas com critério para que quem lê ainda consiga ver de onde vêm as operações.

Siga o que o erro informa

“Cannot find symbol” pode indicar uma importação ausente ou um tipo escrito incorretamente. “Package ... does not exist” aponta para um problema de grafia do pacote, diretório raiz do código-fonte ou dependência. “Is not public ... cannot be accessed from outside package” significa que Java encontrou o tipo, mas o acesso está bloqueado. Adicionar outra importação não corrige esse erro de acesso; examine a declaração da classe e os membros de que você precisa.

Um pacote deve expor as classes e os métodos de que outras partes precisam, mantendo ocultos os detalhes de implementação. Modificadores de acesso permitem impor esse limite. Uma importação pode encurtar um nome, mas não pode atravessar um limite fechado pelas regras de acesso do Java.

Escolha o acesso para um membro de classe

A ausência de modificador significa acesso de pacote para membros comuns de classes e construtores. Não se trata de uma palavra-chave chamada default. Uma classe de nível superior tem apenas duas opções: pública ou com acesso de pacote. Uma classe pública de nível superior é armazenada em um arquivo com seu nome, como ShippingCalculator.java.

Verifique o tipo e a operação

Suponha que a interface do usuário precise construir uma encomenda. Uma classe pública, por si só, não é suficiente:

package com.example.parcels.domain;

public class Parcel {
    private int weightGrams;

    Parcel(int weightGrams) {
        this.weightGrams = weightGrams;
    }
}

O construtor tem acesso de pacote. O código em com.example.parcels.ui pode nomear Parcel, mas não pode chamar new Parcel(1200). Torne esse construtor public se a criação de encomendas fizer parte do serviço público do pacote. Mantenha weightGrams privado e exponha uma operação apropriada em vez de abrir o campo.

O acesso de pacote compara o nome completo do pacote. Um pacote que parece ser pai ou filho não é o mesmo pacote. O código em com.example.parcels não recebe acesso especial às classes auxiliares em com.example.parcels.domain.

Entenda o acesso protegido

protected permite acesso de classes sem relação no pacote que declara o membro, além de subclasses. Entre pacotes, um membro de instância é acessado no contexto de herança da subclasse. Uma subclasse pode usar seu próprio campo herdado, mas não pode usar um objeto arbitrário da superclasse para contornar o limite do pacote.

Por exemplo, se Item declara protected int weightGrams, uma Letter extends Item em outro pacote pode usar this.weightGrams. Dentro de Letter, um parâmetro declarado apenas como Item não permite item.weightGrams; uma referência declarada como Letter permite o acesso herdado. Essa restrição impede que os privilégios da subclasse se tornem acesso geral a cada Item.

Oculte classes auxiliares deliberadamente

Torne ShippingCalculator e feeInCents públicos se a interface os chamar. Uma classe auxiliar WeightBands pode manter acesso de pacote. Assim, o código fora do pacote de domínio depende do comportamento da calculadora, não de como ela armazena a tabela. Substituir essa classe auxiliar exige menos alterações em outros lugares.

Testes podem usar o mesmo nome de pacote da classe testada enquanto ficam em src/test/java. Isso lhes dá acesso de pacote sem colocar código de teste entre arquivos de produção. Isso não concede acesso a campos privados. Tornar cada membro público apenas para satisfazer um teste espalha dependências de detalhes internos; em vez disso, teste o comportamento público ou uma operação útil com acesso de pacote.

Um diagrama de classes UML mostra a estrutura estática: classes, seus membros e relações. Ele ajuda quem lê a ver que tipos de objetos existem e o que oferecem. Não acompanha a ordem das chamadas de métodos durante a execução.

Leia os três compartimentos

Uma caixa de classe tem o nome da classe no topo, os atributos no meio e as operações na parte inferior. Um atributo geralmente representa um campo Java; uma operação representa a assinatura visível de um método. Um esboço pode omitir compartimentos que não atendem ao seu objetivo.

Para uma encomenda, uma representação textual da caixa é:

Parcel
-----------------------------
- weightGrams: int
- recipient: String
-----------------------------
+ Parcel(weightGrams: int, recipient: String)
+ getWeightGrams(): int
+ isHeavierThan(limitGrams: int): boolean

O construtor tem o nome da classe e não tem tipo de retorno. O método isHeavierThan aceita um inteiro chamado limitGrams e retorna um booleano.

Traduza a ordem de nomes e tipos

UML coloca o nome antes do tipo: weightGrams: int. Java coloca o tipo primeiro: int weightGrams. Uma operação segue o mesmo padrão de nome primeiro para parâmetros e depois coloca o tipo de retorno após o parêntese de fechamento.

private int weightGrams;

public boolean isHeavierThan(int limitGrams) {
    return weightGrams > limitGrams;
}

Esse código corresponde a - weightGrams: int e + isHeavierThan(limitGrams: int): boolean. O corpo de um método geralmente não aparece no diagrama; a operação declara o que pode ser chamado, não o algoritmo.

Preserve a visibilidade e as marcações especiais

Os símbolos de visibilidade são + public, - private, # protected e ~ acesso de pacote. Coloque o símbolo antes do nome do membro. Se um diagrama fornecido omitir um símbolo, não invente sua visibilidade; adicione o símbolo pretendido ao documentar o código.

Um membro estático é sublinhado. Ele pertence à classe, e não a cada objeto. Uma classe ou operação abstrata é escrita em itálico ou marcada com {abstract} quando o itálico não é conveniente. A marcação de abstrato significa que uma subclasse precisa fornecer o comportamento ausente antes que um objeto possa ser criado a partir de uma classe concreta.

Uma caixa de interface traz «interface» acima do nome. Por exemplo, ParcelRepository pode oferecer + save(parcel: Parcel): void e + findAll(): List<Parcel>. A caixa declara um contrato; ela não escolhe uma implementação de armazenamento.

Escolha os detalhes de que quem lê precisa

Um esboço de planejamento pode mostrar apenas Parcel, Shipment e suas principais operações. Um diagrama para implementar uma classe precisa de tipos e visibilidade. Listar cada método de acesso rotineiro pode ocultar as relações que o diagrama deveria mostrar. Selecione membros úteis e mantenha-os consistentes com o código: um campo Java privado não deve aparecer com um símbolo público +, e um método estático precisa ser sublinhado.

Uma associação mostra uma ligação estrutural entre objetos. Em Java, um objeto geralmente mantém uma referência a outro em um campo. A linha também pode mostrar quantos objetos são permitidos e em que direção a referência pode ser seguida.

Conte a partir da extremidade oposta

A multiplicidade fica ao lado da classe que ela conta. Se 1..* aparece ao lado de Parcel e 1 ao lado de Shipment, uma remessa tem uma ou mais encomendas, e cada encomenda pertence a exatamente uma remessa. Leia cada extremidade separadamente, começando por um objeto na extremidade oposta.

Uma referência única pode representar 1 ou 0..1; uma coleção representa uma extremidade com vários valores. Uma List Java, por si só, não impõe um limite mínimo. Uma Shipment com uma regra de 1..* encomendas deve rejeitar uma lista inicial vazia e impedir que operações posteriores a deixem vazia. Da mesma forma, uma referência única obrigatória precisa de uma verificação contra null.

Siga a referência

Uma ponta de seta aberta em Parcel significa que uma referência pode ser seguida de Shipment até Parcel. Um diagrama de classes pode deixar a navegabilidade não especificada. Na convenção didática usada aqui, setas marcam referências em uma só direção; uma linha sem marcação pode significar acesso bidirecional ou direção não especificada. Não deduza um campo de volta apenas de uma seta em direção a Parcel.

Um nome de papel como parcels identifica o significado da ligação a partir da remessa. Mostre essa referência como uma associação ou como - parcels: List<Parcel> na caixa. Exibir ambas sem motivo pode fazer um campo parecer dois elementos de estado diferentes.

Escolha o significado de todo–parte

A composição usa um losango preenchido no todo. Uma parte pertence a no máximo um todo composto por vez e normalmente é removida com esse todo, como um pedido e suas linhas de pedido. A agregação usa um losango vazado para um agrupamento mais flexível cujas partes podem existir independentemente. Uma equipe pode agrupar jogadores sem controlar seu tempo de vida.

Java não tem uma palavra-chave de losango e não impõe a propriedade UML apenas porque existe uma lista. Modele composição apenas quando o projeto incluir essa regra de propriedade. Quando o projeto diz apenas que um objeto conhece outro, uma associação simples é mais clara que um losango sem fundamento.

Mostre um uso sem afirmar propriedade

Uma dependência é uma linha tracejada com uma ponta de seta aberta em direção ao tipo usado. Uma calculadora com feeInCents(Parcel parcel) depende de Parcel porque a assinatura de seu método usa esse tipo. Uma dependência é uma relação geral de uso; ela não se limita a código sem campos. Uma associação fornece informações estruturais mais específicas quando um campo é importante para o modelo.

Antes de desenhar uma linha, pergunte o que o código ou o requisito estabelece: uma referência, uma quantidade permitida, um uso ou propriedade. Uma coleção estabelece armazenamento de vários valores, mas por si só não estabelece propriedade exclusiva nem uma quantidade mínima.

Herança e implementação de interface conectam um tipo específico a um mais geral. UML usa um triângulo vazado no tipo geral, mas o estilo da linha distingue as duas relações. Essa distinção indica qual declaração Java escrever.

Leia o triângulo e sua linha

Uma linha contínua com um triângulo vazado em Item significa que uma subclasse como Letter estende Item. Isso é generalização. Uma linha tracejada com um triângulo vazado em ParcelRepository significa que uma classe como InMemoryParcelRepository implementa essa interface. Isso é realização.

O triângulo sempre toca a superclasse ou a interface. Uma seta aberta tracejada, sem o triângulo, indica dependência. O estilo da linha e a ponta da seta juntos transmitem o significado; uma linha tracejada sozinha não basta.

Construa o esqueleto em uma ordem útil

1. Crie cada classe ou interface em seu pacote.
2. Traduza atributos em campos, preservando nomes, tipos e visibilidade.
3. Traduza associações navegáveis em campos de referência ou de coleção.
4. Adicione extends ou implements a partir das linhas de generalização ou realização.
5. Traduza operações em cabeçalhos de métodos e depois forneça seus corpos.

Suponha que uma interface ofereça save e findAll. Uma implementação tem uma associação de vários valores com Parcel, com o papel parcels:

public class InMemoryParcelRepository implements ParcelRepository {
    private List<Parcel> parcels = new ArrayList<>();

    @Override
    public void save(Parcel parcel) {
        parcels.add(parcel);
    }

    @Override
    public List<Parcel> findAll() {
        return new ArrayList<>(parcels);
    }
}

O triângulo com linha tracejada fornece implements ParcelRepository. A associação fornece o campo de lista. As assinaturas das operações fornecem os dois métodos públicos. Os corpos dos métodos são uma escolha de implementação: aqui save acrescenta um objeto, e findAll retorna uma nova lista para que quem chama não possa adicionar ou remover entradas diretamente na lista armazenada. Os próprios objetos de encomenda continuam compartilhados.

Desenhe no sentido inverso

Comece com uma caixa para cada classe ou interface. Um campo de valor simples torna-se um atributo. Uma referência a uma classe do programa torna-se uma associação; uma coleção sugere uma extremidade com vários valores. Examine as verificações de construtores e métodos antes de afirmar que o limite mínimo é um. Traduza extends em uma linha contínua com triângulo e implements em uma linha tracejada com triângulo.

Campos e operações herdados geralmente ficam na caixa da superclasse. Coloque membros novos ou sobrescritos na subclasse. Adicione uma dependência para um parâmetro, tipo de retorno ou uso local quando essa relação ajudar a explicar o projeto.

Pacotes podem envolver suas classes em caixas com formato de pasta e uma pequena aba. Esses grupos ajudam a revelar quais áreas dependem de quais outras. Mantenha atualizado um diagrama de documentação quando o código mudar; identifique um esboço inicial de planejamento para que quem lê compreenda seu objetivo.

Uma Shipment que contém encomendas não é um tipo de Parcel. Sua lista fornece uma relação de “tem”, portanto desenhe uma associação. Use herança para uma relação de “é um tipo de” que o sistema de tipos e o comportamento Java realmente sustentem.

A interface do usuário lê comandos e exibe resultados. A lógica da aplicação contém as regras e os dados sobre os quais esses comandos atuam. Separá-las permite que um teste chame um cálculo diretamente e que outra interface o reutilize sem copiar a regra.

Dê a cada parte uma tarefa clara

TextUI cuida da interação: pede um peso, lê uma linha com Scanner, transforma o texto em um número, chama a lógica e exibe o resultado. ShippingCalculator recebe um peso em gramas e retorna uma tarifa em centavos. Ela não pergunta nada ao usuário nem exibe uma resposta.

Um método chamado printFee mistura essas tarefas se ele calcula e exibe o resultado. Altere a operação da lógica para feeInCents(int weightGrams). A interface pode então exibir "Fee: " + calculator.feeInCents(weightGrams) + " cents". Um teste pode verificar o inteiro retornado com uma asserção sem capturar a saída do console.

Escreva a regra como um valor de retorno

A regra de encomendas cobra 500 centavos para pesos positivos até 2.000 g, 900 centavos até 10.000 g e depois mais 100 centavos para cada bloco iniciado de 1.000 g acima de 10.000 g.

public int feeInCents(int weightGrams) {
    if (weightGrams <= 0) {
        throw new IllegalArgumentException("weight must be positive");
    }
    if (weightGrams <= 2000) {
        return 500;
    }
    if (weightGrams <= 10000) {
        return 900;
    }
    long excess = (long) weightGrams - 10000;
    long startedBlocks = (excess + 999) / 1000;
    return (int) (900 + 100 * startedBlocks);
}

Os dois primeiros ramos que retornam um valor incluem seus limites superiores. Para 12.500 g, o excesso é de 2.500 g. A divisão inteira após a adição de 999 conta três blocos iniciados, resultando em 1.200 centavos. O cálculo intermediário com long também lida com pesos positivos grandes do tipo int sem estouro ao somar 999.

Um peso inválido provoca uma IllegalArgumentException: o método rejeita um argumento que viola sua regra. A interface pode capturar essa exceção e escolher uma mensagem legível. A regra pertence à lógica; a redação da mensagem pertence à interface.

Conecte os objetos em main

Passe o leitor de entrada e a calculadora ao construtor da interface:

public static void main(String[] args) {
    Scanner scanner = new Scanner(System.in);
    ShippingCalculator calculator = new ShippingCalculator();
    TextUI ui = new TextUI(scanner, calculator);
    ui.start();
}

Crie um scanner para o fluxo de entrada e compartilhe-o com a interface. Vários scanners sobre System.in podem interferir na entrada armazenada em buffer uns dos outros. O método main monta o programa; start executa o laço de diálogo.

Ao revisar uma classe, observe suas responsabilidades. Um Scanner ou System.out dentro de uma calculadora de tarifas revela uma mistura de entrada e saída com regras. Uma fórmula de tarifa dentro da interface revela o mesmo problema pelo outro lado. Mova o cálculo para um método com entrada explícita e um resultado; mantenha a interpretação de comandos e o texto de exibição juntos na interface.

Um programa em camadas agrupa classes por responsabilidade. A camada de apresentação cuida do diálogo, a camada de lógica aplica regras e a camada de acesso a dados salva e recupera informações. Uma classe usa outra camada por meio de uma operação clara, sem acessar diretamente seus campos internos.

Posicione as classes de encomendas

O pacote de interface contém TextUI. O pacote de domínio contém Parcel, ShippingCalculator e ParcelService. O pacote de dados contém ParcelRepository e suas implementações de armazenamento. Main monta os objetos acima dessas camadas.

Um comando segue este caminho: o usuário digita “add 1200 Alex”; a interface o interpreta e chama service.register(1200, "Alex"); o serviço valida o peso, cria uma encomenda, salva-a por meio do repositório e retorna 500 centavos; a interface exibe a tarifa. A leitura de texto, a decisão sobre o que é permitido e o armazenamento do resultado têm lugares separados.

Dependa de um contrato

O serviço precisa do comportamento de armazenamento, não de um formato de arquivo específico. Expresse esse comportamento por uma interface:

public interface ParcelRepository {
    void save(Parcel parcel);
    List<Parcel> findAll();
}

O serviço armazena uma referência do tipo ParcelRepository e a recebe no construtor:

public class ParcelService {
    private final ParcelRepository repository;

    public ParcelService(ParcelRepository repository) {
        this.repository = repository;
    }
}

Isso é injeção pelo construtor, uma forma de injeção de dependência: quem chama fornece um colaborador. Um serviço que constrói new FileParcelRepository(...) dentro de seus próprios métodos escolhe o armazenamento em arquivo para si e dificulta testes isolados.

Altere a implementação na montagem

O programa em execução pode criar new ParcelService(new FileParcelRepository("parcels.csv")). Um teste pode fornecer new InMemoryParcelRepository(). Ambas as implementações atendem à mesma interface. Chamadas por meio da interface usam polimorfismo para chegar aos métodos do objeto real.

Com o contrato do repositório inalterado, trocar o armazenamento exige uma nova implementação e uma alteração na montagem. As regras de tarifa e o código de diálogo não precisam saber como os dados são armazenados.

Verifique a direção das dependências com precisão

O caminho descendente de uso dos serviços vai da interface para a lógica e depois para o armazenamento. O domínio não deve importar nem chamar classes da interface. Se a lógica precisar informar um resultado ao usuário, retorne-o à interface. Se a interface salvar diretamente pelo repositório, ela poderá contornar a validação do serviço.

As referências a tipos Java também importam: uma assinatura de repositório que nomeia Parcel depende desse tipo de domínio. Com ParcelRepository no pacote de dados e o serviço no pacote de domínio, esses pacotes se referem um ao outro. Para remover esse ciclo de dependências entre pacotes, coloque a interface do repositório junto aos tipos de domínio e deixe que as implementações de dados a importem. O serviço continua usando o mesmo contrato; apenas sua localização muda. Examine tanto o caminho das chamadas de métodos quanto as importações ao verificar o projeto.

Programas maiores podem primeiro agrupar pacotes por funcionalidade, como pedidos ou clientes, e depois separar responsabilidades dentro de cada funcionalidade. Nomes de pacotes ajudam quem lê a localizar responsabilidades; parâmetros de construtores e assinaturas de métodos mostram as dependências reais.

Um teste unitário chama uma pequena unidade de código com dados de entrada escolhidos e verifica o resultado automaticamente. Ele torna um requisito executável. Executar novamente os testes após uma alteração ajuda a encontrar uma regressão, um defeito em um comportamento que funcionava antes.

Crie um teste Jupiter

JUnit Jupiter é o modelo de programação usado pelo JUnit 5 e 6. JUnit 6 precisa de Java 17 ou posterior. Anotações e asserções de teste usam org.junit.jupiter.api.

Coloque ShippingCalculatorTest.java em src/test/java/com/example/parcels/domain, com a mesma declaração de pacote da calculadora. O diretório raiz separado mantém os testes afastados do código do programa entregue, preservando o acesso ao mesmo pacote.

package com.example.parcels.domain;

import static org.junit.jupiter.api.Assertions.assertEquals;
import org.junit.jupiter.api.Test;

class ShippingCalculatorTest {
    @Test
    void lightParcelCostsBaseFee() {
        ShippingCalculator calculator = new ShippingCalculator();

        int fee = calculator.feeInCents(1500);

        assertEquals(500, fee);
    }
}

A classe e o método de teste podem ter acesso de pacote. Um método de teste retorna void e não pode ser privado. Use o @Test do Jupiter; org.junit.Test do JUnit 4 pertence a outro modelo de programação e não é encontrado pelo mecanismo Jupiter. Asserções do JUnit 4 podem funcionar quando sua biblioteca está disponível, mas importações consistentes do Jupiter mantêm a configuração clara.

Leia preparar–agir–verificar

A primeira parte prepara uma calculadora. A segunda age pedindo a tarifa. A asserção final compara os 500 centavos esperados com o valor retornado. Linhas em branco tornam essas tarefas fáceis de identificar. Exibir apenas fee deixaria para uma pessoa a decisão sobre sua correção; a asserção torna essa decisão parte do teste.

assertEquals(expected, actual) coloca o requisito primeiro e o resultado observado em segundo. Uma mensagem opcional vem por último, como em assertEquals(500, fee, "fee for 1,500 g"). Inverter os dois primeiros argumentos geralmente mantém o resultado de aprovação ou falha para esses valores, mas inverte o significado do relatório de falha.

Escolha a asserção adequada

Use assertTrue ou assertFalse para um booleano e assertNull ou assertNotNull quando a presença de um objeto for o resultado. Verificações de igualdade de objetos usam equals; sem uma sobrescrita, dois objetos distintos com campos correspondentes ainda podem ser considerados diferentes.

Resultados em ponto flutuante precisam de uma tolerância apropriada. O cálculo 0.1 + 0.2 produz 0.30000000000000004 em um double Java:

assertEquals(0.3, 0.1 + 0.2, 1e-9);

O terceiro argumento permite uma diferença absoluta de até 0.000000001. Escolha uma tolerância adequada ao cálculo; uma tolerância excessivamente grande pode ocultar um erro significativo. Cálculos com centavos inteiros não precisam de tolerância decimal.

Leia uma falha

Execute um teste pela IDE ou pela ferramenta de construção. Um relatório como “expected: <500> but was: <900>” informa os resultados exigido e observado; o rastreamento da pilha aponta para a asserção. Uma exceção inesperada também faz um teste falhar. Verde significa que os casos verificados passaram; escolher esses casos continua sendo uma parte separada do teste.

Um conjunto útil de testes verifica como a especificação divide as entradas em casos. Uma entrada comum raramente testa uma regra inteira. Casos de valor-limite no limite e imediatamente ao seu lado são especialmente bons para encontrar uma condição escrita com o operador relacional errado.

Divida o espaço de entradas

Uma classe de equivalência agrupa entradas que devem ser tratadas da mesma forma. A regra de envio tem pesos inválidos em zero ou abaixo, uma faixa de 500 centavos até 2.000 g, uma faixa de 900 centavos até 10.000 g e um cálculo por bloco iniciado acima disso. Escolha entradas representativas das classes e depois examine seus limites.

Alterar <= 2000 para < 2000 afeta exatamente 2.000 g. Um teste com 1.500 g continua passando. Acima de 10.000 g, teste tanto um bloco inteiro quanto o primeiro grama do bloco seguinte para verificar o arredondamento para cima.

Os valores esperados vêm do requisito e do cálculo manual. Para 12.500 g, o excesso é de 2.500 g, exigindo três blocos iniciados, portanto o resultado esperado é 1.200 centavos. Executar o método e copiar sua resposta para o teste também copiaria qualquer defeito.

Teste entradas rejeitadas

Um teste de exceção fornece ao JUnit a operação a executar:

assertThrows(IllegalArgumentException.class,
    () -> calculator.feeInCents(0));

A expressão () -> ... é uma lambda: um pequeno trecho de código fornecido ao JUnit. JUnit o executa dentro da verificação. Chamar o método antes de fornecê-lo à asserção deixaria a exceção escapar antes que a verificação pudesse examiná-la.

assertThrows aceita o tipo de exceção nomeado ou uma subclasse. Ele falha se a operação terminar normalmente ou lançar um tipo incompatível. Ele retorna a exceção, portanto uma mensagem exigida pode ser verificada:

IllegalArgumentException error = assertThrows(
    IllegalArgumentException.class,
    () -> calculator.feeInCents(0));
assertEquals("weight must be positive", error.getMessage());

Dê um nome legível a cada cenário

Nomes como zeroWeightIsRejected e feeIsBaseFeeAtExactly2000Grams identificam o comportamento pretendido. Um teste pode ter várias asserções quando elas verificam o mesmo resultado. Após adicionar encomendas de 1.200 g e 800 g a uma remessa, verificar uma contagem de duas e um peso total de 2.000 g descreve esse único cenário. assertAll pode agrupar verificações para que todas as falhas sejam relatadas.

Verifique objetos alterados por meio de seu comportamento, como parcelCount() e totalWeightGrams(), em vez de expor campos privados para testes. Assim, uma refatoração pode alterar detalhes de armazenamento preservando as verificações. Cobertura completa de linhas significa que os testes executaram as linhas; ela ainda pode deixar passar um limite incorreto ou uma entrada inválida não testada.

Cada teste deve preparar tudo de que precisa. Um teste que só passa depois que outro adicionou dados depende de um histórico oculto. Esses testes tornam-se difíceis de confiar quando um executor altera a ordem ou executa apenas um método.

Crie um novo conjunto de teste

Um conjunto de dados e objetos de teste é o conjunto de objetos e dados que um teste usa. Coloque a preparação repetida de cada teste em @BeforeEach:

class ShipmentTest {
    private Shipment shipment;

    @BeforeEach
    void setUp() {
        shipment = new Shipment();
    }

    @Test
    void newShipmentIsEmpty() {
        assertEquals(0, shipment.parcelCount());
    }

    @Test
    void addingParcelIncreasesCount() {
        shipment.add(new Parcel(1200, "Alex"));
        assertEquals(1, shipment.parcelCount());
    }
}

A preparação é executada antes de cada método. O segundo teste não altera a remessa usada pelo primeiro. Por padrão, Jupiter também cria uma nova instância da classe de teste para cada método de teste. Campos estáticos mutáveis continuam compartilhados, portanto uma lista estática ainda pode transmitir estado entre essas instâncias.

@AfterEach faz a limpeza após cada teste. @BeforeAll e @AfterAll são executados uma vez para a classe e são estáticos no ciclo de vida padrão. Dados de referência compartilhados somente para leitura podem ser adequados para uma preparação feita uma vez por classe; objetos que mudam geralmente precisam ser criados novamente para cada teste. Os testes devem funcionar individualmente, sem depender da ordem no arquivo-fonte.

Use um corpo de teste para uma tabela

Um teste parametrizado executa a mesma verificação de comportamento para várias linhas:

@ParameterizedTest
@CsvSource({"1, 500", "2000, 500", "2001, 900",
            "10000, 900", "10001, 1000"})
void feeMatchesTable(int grams, int expected) {
    assertEquals(expected,
        new ShippingCalculator().feeInCents(grams));
}

Cada linha é uma invocação separada com seu próprio relatório. @ValueSource(ints = {0, -5}) fornece um inteiro por invocação para testes de entradas inválidas. Anotações de testes parametrizados vêm de org.junit.jupiter.params; CsvSource e ValueSource estão em seu pacote provider. A dependência agregadora junit-jupiter inclui o módulo de testes parametrizados.

@DisplayName adiciona um rótulo legível ao relatório. @Disabled registra um teste ignorado com um motivo; uma verificação ignorada não fornece evidência de aprovação para o comportamento que testaria.

Controle o ambiente

Um teste de serviço pode receber um InMemoryParcelRepository, uma implementação simplificada para testes funcional que armazena encomendas em memória. Isso evita o conteúdo de arquivos reais e isola a lógica. Passe um Scanner construído a partir de uma cadeia de caracteres conhecida a uma interface de texto ao testar seu tratamento de entrada. Uma data fixa ou um Random com semente fixa também torna previsível uma entrada externa.

Um teste instável muda seu resultado entre execuções sem uma alteração relevante no código. Dados mutáveis compartilhados, o horário atual, valores aleatórios não controlados e arquivos remanescentes são causas comuns. Dê ao teste controle dessas entradas. Mantenha métodos auxiliares pequenos e a preparação legível; um conjunto de teste que constrói muitos objetos sem relação pode revelar que a classe testada tem tarefas demais.

O desenvolvimento orientado por testes (TDD) começa uma mudança de comportamento com um teste. Um ciclo curto torna visível o comportamento ausente, implementa-o e depois melhora a estrutura do código. Uma lista de testes guarda os casos que ainda precisam ser explorados sem exigir que todos sejam escritos de uma vez.

Escolha um item da lista de testes

Para um verificador de anos bissextos gregorianos, liste quatro comportamentos: um ano comum não bissexto, um ano divisível por quatro, um ano de século que não é divisível por 400 e um ano de século que é divisível por 400. Esses casos representam partes diferentes da regra.

Vermelho: escreva um teste e execute-o. Um método ausente pode causar um erro de compilação. Quando o método existir, verifique se o teste falha para o comportamento que você pretende adicionar. Uma asserção ausente, a chamada do método errado ou um teste não encontrado podem tornar enganoso um resultado aparentemente verde. Um novo caso também pode já ser satisfeito pelo código existente; examine esse resultado antes de alterar a implementação.

Verde: adicione o código mais simples que faça o novo teste e todos os anteriores passarem. Refatorar: melhore a estrutura sem alterar o comportamento e execute novamente os testes após cada pequena alteração. Depois, escolha o próximo caso.

Deixe os casos desenvolverem a regra

A primeira verificação é assertFalse(LeapYears.isLeapYear(2023)). Criar o método com return false; faz esse caso passar. É um primeiro passo deliberado, não uma regra de calendário concluída.

A próxima verificação, assertTrue(LeapYears.isLeapYear(2024)), falha. Altere o método para return year % 4 == 0;. Ambos os casos agora passam.

Em seguida, assertFalse(LeapYears.isLeapYear(1900)) expõe a exceção dos anos de século. Alterar a expressão para year % 4 == 0 && year % 100 != 0 faz esses três testes passarem.

Por fim, assertTrue(LeapYears.isLeapYear(2000)) expõe a exceção à regra dos anos de século. A implementação fica:

public static boolean isLeapYear(int year) {
    return year % 400 == 0
        || (year % 4 == 0 && year % 100 != 0);
}

Execute as quatro verificações após a alteração. Cada nova falha apontou para uma parte ausente do comportamento, em vez de pedir que você depurasse uma implementação grande e inacabada.

Melhore a estrutura enquanto os testes estão verdes

Refatoração altera nomes ou organização preservando o comportamento. Renomear um método, extrair um método auxiliar, remover lógica repetida e mover uma classe para um pacote mais adequado são refatorações quando o comportamento observável permanece igual. Alterar a tarifa cobrada em um limite é uma mudança de comportamento e precisa de um teste que descreva essa alteração.

Se uma limpeza fizer um teste falhar, restabeleça o comportamento pretendido antes de adicionar outra funcionalidade. Pequenas alterações ajudam a localizar a causa de uma falha. Pular a limpeza deixa código que passa nos testes, mas se torna mais difícil de ampliar; escrever uma implementação grande para muitos casos futuros cria mais código para examinar quando a próxima verificação falhar.

TDD depende da qualidade dos requisitos e dos casos selecionados. Uma regra mal compreendida pode aparecer tanto no teste quanto na implementação. A lógica com entradas e saídas claras é um ponto de partida útil porque o resultado esperado pode ser declarado independentemente e verificado rapidamente.

Uma ferramenta de construção transforma arquivos-fonte em um resultado verificado e empacotado. Maven lê uma descrição do projeto, baixa bibliotecas declaradas, compila código, executa testes e cria um artefato. A mesma descrição fornece à linha de comando e à IDE uma visão compartilhada do projeto.

Use a estrutura padrão

Coloque o código Java de produção em src/main/java, os testes em src/test/java, os recursos de produção em src/main/resources e os dados de teste em src/test/resources. As pastas de pacotes começam abaixo de cada diretório raiz do código-fonte Java. Maven grava a saída gerada em target; edite os arquivos-fonte, não as cópias compiladas nessa pasta.

O arquivo pom.xml na raiz do projeto, o Project Object Model, identifica o projeto usando coordenadas: groupId, artifactId e version. Por exemplo, com.example:parcels:1.0-SNAPSHOT identifica uma versão de desenvolvimento do programa de encomendas. Uma dependência de biblioteca também tem coordenadas.

Declare JUnit para testes

A seguir está uma configuração Maven pequena e completa. Ela compila para Java 17 e seleciona um executor de testes compatível com Jupiter:

<project xmlns="http://maven.apache.org/POM/4.0.0">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.example</groupId>
  <artifactId>parcels</artifactId>
  <version>1.0-SNAPSHOT</version>
  <properties>
    <maven.compiler.release>17</maven.compiler.release>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  </properties>
  <dependencies>
    <dependency>
      <groupId>org.junit.jupiter</groupId>
      <artifactId>junit-jupiter</artifactId>
      <version>6.1.3</version>
      <scope>test</scope>
    </dependency>
  </dependencies>
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>3.14.1</version>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-surefire-plugin</artifactId>
        <version>3.5.4</version>
      </plugin>
    </plugins>
  </build>
</project>

Maven obtém dependências de repositórios, normalmente o Maven Central, e as armazena em cache em .m2/repository dentro de sua pasta pessoal. Bibliotecas necessárias para uma dependência são dependências transitivas. O escopo de teste disponibiliza JUnit para compilar e executar testes, não para a compilação do código principal nem para o caminho de classes do programa em execução. Um JAR comum mantém os JARs de suas dependências separados, a menos que o empacotamento seja configurado para reuni-los.

Solicite uma fase do ciclo de vida

O ciclo de vida principal passa por compile, test, package e install, entre outras fases. Solicitar package também executa as fases anteriores. Com o inicializador, ./mvnw test compila e testa; ./mvnw package também cria o JAR em target; ./mvnw install adicionalmente coloca o artefato no repositório local. O ciclo de vida separado de limpeza, ./mvnw clean, remove a saída gerada.

Uma falha de teste interrompe a construção normal antes do empacotamento de um novo artefato. Um JAR antigo ainda pode estar presente até a limpeza, portanto sua presença não comprova que a construção mais recente foi bem-sucedida.

Torne visível a descoberta de testes

Os padrões do Surefire incluem por padrão nomes que começam com Test ou terminam com Test, Tests ou TestCase. ShippingChecks não corresponde a eles; use ShippingCalculatorTest e examine a quantidade de testes informada. Testes colocados em src/main/java não podem usar uma dependência com escopo de teste.

O Maven Wrapper, mvnw ou mvnw.cmd no Windows, executa a versão do Maven especificada pelo projeto. Use um projeto que inclua seus arquivos de inicialização; um POM sozinho não cria os scripts. A partir da raiz do projeto, o inicializador fornece um comando de construção consistente sem uma instalação separada do Maven.

Gradle descreve uma construção com um script e executa tarefas com suas dependências. Um script Kotlin chama-se build.gradle.kts; um script Groovy chama-se build.gradle. Plugins fornecem tarefas, e configurações de dependência indicam onde as bibliotecas são necessárias.

Configure uma aplicação e Jupiter

Um settings.gradle.kts na raiz do projeto pode conter rootProject.name = "parcels". Um script de construção Kotlin correspondente é:

plugins {
    application
}

repositories {
    mavenCentral()
}

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(17)
    }
}

dependencies {
    testImplementation(platform("org.junit:junit-bom:6.1.3"))
    testImplementation("org.junit.jupiter:junit-jupiter")
    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
}

application {
    mainClass = "com.example.parcels.Main"
}

tasks.test {
    useJUnitPlatform()
}

O plugin application fornece tarefas de construção Java e adiciona run. mavenCentral() seleciona um repositório de dependências. A BOM, ou lista de materiais, alinha as versões dos módulos JUnit, portanto a versão aparece uma vez. testImplementation fornece bibliotecas necessárias para compilar e executar testes. testRuntimeOnly fornece o inicializador apenas durante sua execução. Bibliotecas do código principal usam implementation, que também as disponibiliza para o código de teste.

useJUnitPlatform() seleciona a plataforma que executa testes Jupiter. Adicionar bibliotecas Jupiter sem configurar o executor pode deixar esses testes sem serem encontrados. O Gradle atual falha quando há arquivos-fonte de teste, mas nenhum teste é encontrado sob sua configuração padrão; examine a saída e a configuração da tarefa de teste em vez de remover a verificação.

Execute tarefas com o inicializador

Use o inicializador incluído no projeto: ./gradlew test executa testes; ./gradlew build compila, testa e empacota; ./gradlew run inicia a classe principal configurada; e ./gradlew clean remove build. No Windows, use gradlew.bat. Gradle usa a mesma estrutura de código-fonte principal e de teste que Maven e grava a saída gerada em build.

Uma tarefa marcada como UP-TO-DATE tem entradas e saídas monitoradas inalteradas, portanto Gradle reutiliza seu resultado anterior. Essa mensagem é diferente de uma execução de teste recém-realizada. O relatório HTML de testes está em build/reports/tests/test/index.html.

Encontre a etapa que falhou

Comece pelo primeiro erro útil. “Cannot find symbol” durante a compilação principal aponta para o código, a importação ou a dependência mencionados. A ausência de org.junit.jupiter.api durante a compilação dos testes aponta para a configuração da dependência de teste; o mesmo erro durante a compilação principal pode significar que um teste foi colocado na pasta de código-fonte principal. Um erro de resolução de dependência aponta para coordenadas, acesso ao repositório ou disponibilidade da rede.

Uma falha durante a execução de um teste é diferente: o teste foi compilado e encontrado, mas sua verificação falhou. Se “expected: <500> but was: <900>” aparecer no limite de tarifa de 2.000 g, examine a comparação que escolhe a faixa. Alterar dependências não corrigirá esse cálculo.

Maven oferece uma descrição declarativa em XML com fases fixas de ciclo de vida. Gradle oferece scripts e tarefas configuráveis, incluindo a possibilidade de pular trabalho atualizado. Ambos automatizam construções Java repetíveis; use a ferramenta escolhida para o projeto e leia a primeira falha que permita agir antes de alterar o código.