O mindqa-db-commons é uma biblioteca Java para automação de testes que simplifica consultas e operações de INSERT, UPDATE e DELETE em SQL Server, PostgreSQL, Oracle e MySQL. Ela centraliza a configuração das conexões por variáveis de ambiente ou arquivos .properties, permitindo usar uma conexão padrão ou selecionar conexões e bases diferentes no mesmo teste.

Requer Java 17 ou superior.

Adicione a dependência ao projeto de automação:

<dependency>
    <groupId>io.github.raialmeida</groupId>
    <artifactId>mindqa-db-commons</artifactId>
    <version>4.0.1</version>
    <scope>test</scope>
</dependency>

testImplementation 'io.github.raialmeida:mindqa-db-commons:4.0.1'

tasks.withType(Test).configureEach {
    useJUnitPlatform()

    ['db.config', 'db.env'].each { propertyName ->
        String propertyValue = System.getProperty(propertyName)
        if (propertyValue != null) {
            systemProperty propertyName, propertyValue
        }
    }
}

# Carrega database.properties automaticamente
./gradlew test

# Seleciona qualquer arquivo .properties no classpath ou sistema de arquivos
./gradlew test -Ddb.config=config-hml.properties

# Seleciona database-hml.properties no classpath
./gradlew test -Ddb.env=hml

# Executa somente uma classe de teste
./gradlew test --tests "CadastroClienteTest"

DB_CONFIG=config-hml.properties ./gradlew test
DB_ENV=hml ./gradlew test

libraryDependencies += "io.github.raialmeida" % "mindqa-db-commons" % "4.0.1" % Test

def ivyDeps = Agg(
  ivy"io.github.raialmeida:mindqa-db-commons:4.0.1"
)

<dependency org="io.github.raialmeida"
            name="mindqa-db-commons"
            rev="4.0.1"
            conf="test" />

@Grab(group='io.github.raialmeida', module='mindqa-db-commons', version='4.0.1')

:dependencies [[io.github.raialmeida/mindqa-db-commons "4.0.1"]]

test.with _('io.github.raialmeida:mindqa-db-commons:jar:4.0.1')

Crie src/test/resources/database.properties no projeto consumidor e defina uma conexão padrão. Esse é o arquivo carregado automaticamente quando nenhum seletor de arquivo ou ambiente é informado. Por padrão, a biblioteca abre e fecha uma conexão física por operação. Para reutilizar conexões físicas, configure o pool conforme Erros e solução de problemas.

Você pode manter todas as conexões no mesmo arquivo. O valor de DB_DEFAULT_CONNECTION define a conexão usada por DatabaseService.select(...), DatabaseService.execute(...) e DatabaseService.database(...). Ele é obrigatório para essas chamadas quando existem dois ou mais prefixos ou conexões nomeadas e não há uma configuração simples DB_*. Chamadas com DatabaseService.connection("nome") selecionam o destino explicitamente e não dependem dessa variável.

No arquivo, também são aceitas chaves com pontos e letras minúsculas, como postgresql.host e oracle.pass. Variáveis de ambiente usam as chaves equivalentes em maiúsculas e com sublinhado, como POSTGRESQL_HOST e ORACLE_PASS.

DB_DEFAULT_CONNECTION=postgresql

POSTGRESQL_HOST=localhost
POSTGRESQL_PORT=5432
POSTGRESQL_USER=qa_user
POSTGRESQL_PASS=senha
POSTGRESQL_NAME=qa_database

SQLSERVER_HOST=localhost
SQLSERVER_PORT=1433
SQLSERVER_USER=qa_user
SQLSERVER_PASS=senha
SQLSERVER_NAME=qa_database

MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=qa_user
MYSQL_PASS=senha
MYSQL_NAME=qa_database

ORACLE_HOST=localhost
ORACLE_PORT=1521
ORACLE_USER=qa_user
ORACLE_PASS=senha
ORACLE_NAME=FREEPDB1

Nesse exemplo, as chamadas estáticas usam PostgreSQL. Para trocar o padrão, altere DB_DEFAULT_CONNECTION para sqlserver, mysql ou oracle. Para usar as quatro conexões no mesmo teste, consulte Múltiplas conexões e bases.

Também é possível configurar uma conexão por variáveis de ambiente, sem criar um arquivo .properties. Defina-as no processo que executará os testes, seja pelo terminal, pela IDE, pelo pipeline ou pelo gerenciador de build:

export DB_TYPE=postgres
export DB_HOST=localhost
export DB_PORT=5432
export DB_USER=qa_user
export DB_PASS=senha
export DB_NAME=qa_database

Este bloco usa somente variáveis de ambiente. Se mantiver o arquivo do exemplo anterior, DB_DEFAULT_CONNECTION=postgresql continuará selecionando POSTGRESQL_*. Para usar a configuração simples DB_* nesse caso, exporte também DB_DEFAULT_CONNECTION=""; o valor vazio substitui o seletor do arquivo.

Depois, execute os testes normalmente. Por exemplo:

# Maven
mvn test

# Gradle
./gradlew test

As variáveis de ambiente têm prioridade sobre os valores do arquivo. Para vários servidores simultâneos, consulte Múltiplas conexões e bases.

Quando existem várias conexões configuradas, cada variável com prefixo de banco altera somente aquele destino. O exemplo abaixo complementa o arquivo com os quatro motores mostrado acima: host, usuário, senha e base continuam vindo dele.

export DB_DEFAULT_CONNECTION=postgresql
export POSTGRESQL_PORT=5478
export SQLSERVER_PORT=1433
export MYSQL_PORT=3306
export ORACLE_PORT=1521

Assim, uma chamada estática usa PostgreSQL na porta 5478:

import io.mindqa.database.DatabaseService;

DatabaseService.select("SELECT * FROM clientes");

Para uma conexão nomeada, configure o prefixo do nome e selecione-o explicitamente:

export DB_CONNECTIONS_REPLICA_TYPE=postgres
export DB_CONNECTIONS_REPLICA_HOST=replica.qa.interno
export DB_CONNECTIONS_REPLICA_PORT=5478
export DB_CONNECTIONS_REPLICA_USER=qa_user
export DB_CONNECTIONS_REPLICA_PASS=senha
export DB_CONNECTIONS_REPLICA_NAME=qa_database

import io.mindqa.database.DatabaseService;

DatabaseService.connection("replica")
        .select("SELECT * FROM clientes");

Use os nomes ou aliases das colunas para acessar os valores do mapa. O teste pressupõe cliente-1 cadastrado com nome Cliente QA.

import io.mindqa.database.DatabaseService;
import org.junit.jupiter.api.Test;

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

@Test
void deveConsultar() {
    // var infere List<Map<String, Object>> para esta variável local.
    var clientes = DatabaseService.select(
            "SELECT nome FROM clientes WHERE id = ?", "cliente-1");

    assertEquals(1, clientes.size());
    assertEquals("Cliente QA", clientes.get(0).get("nome"));
}

Depois de configurar o banco, execute uma operação diretamente no teste. Para a asserção abaixo passar, prepare previamente o registro cliente-001:

import io.mindqa.database.DatabaseService;

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

int removidos = DatabaseService.execute(
        "DELETE FROM clientes WHERE id = ?", "cliente-001");
assertEquals(1, removidos);

O método retorna a quantidade de registros afetados.