Ci sono diversi modi di eseguire i test con PgTAP. È possibile usare pg_prove, uno script installabile attraverso il CPAN, oppure si può scrivere una funzione plpgsql che esegua i test.

In questo esempio, useremo una funzione.

Creiamo un file che contenga i test, chiamamolo risultati_test.sql.

Scriviamo la funzione che lancia i test direttamente nel file, con il nostro editr preferito.

CREATE OR REPLACE FUNCTION risultati_test()
RETURNS SETOF TEXT
AS $$
BEGIN
-- Controlliamo la presenza degli oggetti:
-- Tabella foo
RETURN NEXT tables_are(
'public',
ARRAY[ 'foo' ]
);
-- Schema nuovo_schema
RETURN NEXT schemas_are(
ARRAY['public','nuovo_schema']
);
-- Controlla che sia presente la funzione say_hello
RETURN NEXT can(
ARRAY['say_hello']
);
-- Controlla che la funzione say_hello sia scritta in SQL
RETURN NEXT function_lang_is(
'say_hello',
'sql'
);
-- Controlla che la funzione say_hello non generi errori
RETURN NEXT lives_ok(
'SELECT say_hello()'
);
-- Controlla che la tabella foo contenga esattamente certi valori
-- provate a cambiare uno dei valori ed osservare come si comporta il test
RETURN NEXT results_eq(
'SELECT 2ndquadrant_italia_mod.txt 2ndquadrant_italia.txt da_installare_pandoc hdoisajds.sh risultati step2 FROM foo',
'VALUES (1),(2),(3),(4),(5)'
);
END;
$$ LANGUAGE plpgsql;

Adesso creiamo il file che esegue questa funzione, chiamiamolo test.sql

BEGIN;
i risultati_test.sql
SELECT PLAN(6); -- Necessario!
SELECT risultati_test();
ROLLBACK;

2ndquadrant_italia_mod.txt 2ndquadrant_italia.txt da_installare_pandoc hdoisajds.sh risultati step2 La prima riga dà inizio ad una transazione. È consigliato inserire i test in una transazione che esegua un rollback prima di terminare, così da essere sicuri che lo stato del databse venga mantenuto intatto.

2ndquadrant_italia_mod.txt 2ndquadrant_italia.txt da_installare_pandoc hdoisajds.sh risultati step2 Successivamente, tramite il comando di psql i, importiamo il file risultati_test.sql, che crea la funzione che lancia i test.

2ndquadrant_italia_mod.txt 2ndquadrant_italia.txt da_installare_pandoc hdoisajds.sh risultati step2 La riga successiva, SELECT PLAN(6);, serve a specificare il numero di test che intendiamo eseguire (6 in questo caso). È necessaria e controlla che l’esecuzione di un numero di test diverso rispetto a quello specificato, restituisca un fallimento.

2ndquadrant_italia_mod.txt 2ndquadrant_italia.txt da_installare_pandoc hdoisajds.sh risultati step2 La riga SELECT risultati_test(); lancia la funzione che esegue i test.

Abbiamo finito di scrivere i nostri test, possiamo eseguirli con:

psql -f test.sql pgtap_db

Il risultato dovrebbe essere:

BEGIN
CREATE FUNCTION
plan
------
1..6
(1 row)
testfunction
------------------------------------------------------
ok 1 - Schema public should have the correct tables
ok 2 - There should be the correct schemas
ok 3 - Schema pg_temp_2 or pg_catalog or public can
ok 4 - Function say_hello() should be written in sql
ok 5
ok 6
(6 rows)
ROLLBACK

Si spiega da solo, no? :)

In effetti, lo scopo del protocollo TAP è di essere il più comprensibile possibile. Una serie di ok (in caso di successo) e di not ok (in caso di fallimento) rendono estremamente facile l’interpretazione dei test.

2ndQuadrant Italia utilizza estensivamente PgTAP, il tempo speso a scrivere i test risulta di vitale importanza per la manutenzione dei nostri progetti.

Non mi dilungherò a descrivere il motivo per cui i test sono importanti, specialmente nell’ottica dello sviluppo agile, che 2ndQuadrant adotta con successo.

PgTAP, sfruttando una sintassi estremamente semplice, permette di testare a fondo il proprio database.

Presupponendo che PgTAP sia stato installato correttamente in un database chiamato pgtap_db, procediamo con la creazione di alcuni oggetti sui quali eseguiremo dei test.

Per informazioni circa l’installazione di PgTAP in un determinato database, rimando alla documentazione ufficiale.

$ psql -c "CREATE TABLE foo AS SELECT generate_series(1,5) AS x" pgtap_db
SELECT 1
$ psql -c "CREATE SCHEMA nuovo_schema" pgtap_db
CREATE SCHEMA
$ psql -c "CREATE FUNCTION say_hello() RETURNS TEXT LANGUAGE SQL AS $$SELECT 'Hello World'::TEXT$$;" pgtap_db
CREATE FUNCTION

Tipi di utilizzo

PgTAP può essere utilizzato per testare qualsiasi aspetto del database. In particolare:

2ndquadrant_italia_mod.txt 2ndquadrant_italia.txt da_installare_pandoc hdoisajds.sh risultati step2 Presenza di oggetti nel database 2ndquadrant_italia_mod.txt 2ndquadrant_italia.txt da_installare_pandoc hdoisajds.sh risultati step2 Controllo dell'esecuzione di query 2ndquadrant_italia_mod.txt 2ndquadrant_italia.txt da_installare_pandoc hdoisajds.sh risultati step2 Controllo dei risultati di una query 2ndquadrant_italia_mod.txt 2ndquadrant_italia.txt da_installare_pandoc hdoisajds.sh risultati step2 Altro

Descriverò in ordine questi aspetti e poi vedremo un esempio pratico.

Presenza di oggetti nel database

Si può controllare l'esistenza di qualsiasi tipo di oggetto nel database. Questo tipo di funzioni ha più o meno la stessa firma, in particolare:

*tipo_di_oggetto*_are( [schema,]  [,description] )

Dove:

2ndquadrant_italia_mod.txt 2ndquadrant_italia.txt da_installare_pandoc hdoisajds.sh risultati step2 tipo_di_oggetto è la categoria di oggetti di cui vogliamo testare la presenza, ad esempio tabelle (tables), funzioni (functions), schemi (schemas) ecc.

2ndquadrant_italia_mod.txt 2ndquadrant_italia.txt da_installare_pandoc hdoisajds.sh risultati step2 schema definisce lo schema in cui gli oggetti devono trovarsi, questo parametro ha senso solo se non si sta testando la presenza dello schema stesso.

2ndquadrant_italia_mod.txt 2ndquadrant_italia.txt da_installare_pandoc hdoisajds.sh risultati step2 array_di_nomi è un array contenente i nomi degli oggetti che devono essere presenti perchè il test abbia successo

Importante: Per avere successo, tutti gli elementi specificati nell'array devono essere presenti. In caso di assenza di almeno uno degli elementi, il test fallirà.

2ndquadrant_italia_mod.txt 2ndquadrant_italia.txt da_installare_pandoc hdoisajds.sh risultati step2 description è una descrizione del test

Nota: Ovviamente, nel caso di schemas_are, il primo parametro, schema, viene omesso.

Controllo dell'esecuzione di query

È possibile testare in modo semplice che una query venga eseguita senza o con errori. Per farlo sono disponibili le funzioni:

throws_ok( query [, errcode] [, errmsg] [, description] )
lives_ok( query [, description] )
performs_ok( query, milliseconds [, description])

Queste tre funzioni controllano rispettivamente:

2ndquadrant_italia_mod.txt 2ndquadrant_italia.txt da_installare_pandoc hdoisajds.sh risultati step2 Che la query generi un'eccezione. È possibile specificare l'errore voluto tramite il parametro errcode

2ndquadrant_italia_mod.txt 2ndquadrant_italia.txt da_installare_pandoc hdoisajds.sh risultati step2 Che la query non generi un'eccezione

2ndquadrant_italia_mod.txt 2ndquadrant_italia.txt da_installare_pandoc hdoisajds.sh risultati step2 Che la query termini entro milliseconds millisecondi

Controllo dei risultati di una query

Spesso si ha bisgno di controllare che una query restituisca esattamente un certo insieme di risultati. PgTAP ha diverse funzioni per questo scopo, la principale è:

results_eq( sql, array [, description] )

Molto intuitivamente, questo test passerà se l'insieme di risultati della query sarà esattamente uguale ai valori presenti in array. Nell'esempio completo presente più in basso, vedremo come sfruttare questa funzione.

Altro

Vi sono poi altri tipi di test, ma citiamo qui solo i più importanti. Per una lista completa invitiamo a consultare la documentazione ufficiale.

2ndquadrant_italia_mod.txt 2ndquadrant_italia.txt da_installare_pandoc hdoisajds.sh risultati step2 Per controllare qualsiasi elemento usando un'espressione regolare:

matches( anyelement, regex [, description] )

2ndquadrant_italia_mod.txt 2ndquadrant_italia.txt da_installare_pandoc hdoisajds.sh risultati step2 Per controllare che un utente sia un superutente:

is_superuser( user [, description] )

2ndquadrant_italia_mod.txt 2ndquadrant_italia.txt da_installare_pandoc hdoisajds.sh risultati step2 Per controllare che una funzione sia scritta in un determinato linguaggio:

function_lang_is( [schema,] function [, args[]] , language [, description])

2ndquadrant_italia_mod.txt 2ndquadrant_italia.txt da_installare_pandoc hdoisajds.sh risultati step2 Per stampare messaggi di diagnostica che non interferiscano con i test:

diag( text )

Nel prossimo articolo vedremo un esempio pratico, dove eseguiremo dei test su un set di oggetti creati per l'occasione.

A presto!