Tutoriel avancé sur AssertJ-DB : les concepts et assertions

La classe DataSource est un classique pour toute personne avec un peu d'expérience en Java. Donc, l'article ne développera pas plus ce concept. L'important est juste de connaître que c'est un moyen de connexion possible.

Pour les utilisateurs de DBSetup, cela correspond aux DataSourceDestination.

Pour les environnements de tests sans DataSource disponible, il existe un autre moyen de connexion : Source.

Source prend en paramètres de constructeur : l'URL de la base de données, l'utilisateur et le mot passe de connexion.

// Instanciation d'un objet Source équivalent à l'objet DataSource du premier exemple
Source source = new Source("jdbc:h2:mem:test", "user", "password");

Pour les utilisateurs de DBSetup, cela correspond aux DriverManagerDestination.

Il est possible de consulter plus d'informations dans la documentation officielle de Source.

Un objet Table correspond tout simplement à une table dans la base de données. Sa construction nécessite au minimum un moyen de connexion à la base et le nom de la table.

// Les deux instanciations ci-dessous correspondent à des objets Table
// sur la table "membres" qui est dans la base H2 en mémoire
// Instanciation d'un objet Table grâce à un objet DataSource
Table table1 = new Table(dataSource, "membres");
// Instanciation d'un objet Table grâce à un objet Source
Table table2 = new Table(source, "membres");

Table comporte deux autres paramètres optionnels, mais qui s'ajoutent ensemble. Le premier paramètre supplémentaire indique les colonnes à inclure dans le traitement; tandis que le second paramètre supplémentaire indique les colonnes à exclure. Si un de ces paramètres n'est pas à prendre en compte, il est renseigné à null.

// Instanciation équivalente à table1 ou table2
Table table3 = new Table(source, "membres", null, null);
// table4 ne contient que les colonnes "id" et "nom" et aucune autre
Table table4 = new Table(source, "membres", new String[] { "id", "nom" }, null);
// table5 contient toutes les colonnes à l'exception de "date_naissance"
Table table5 = new Table(source, "membres", null, new String[] { "date_naissance" });
// table6 ne contient que la colonne "nom" car la colonne "id" est incluse et exclue
Table table6 = new Table(source, "membres", new String[] { "id", "nom" }, new String[] { "id" });

L'instance table4 ne contient que les colonnes ID et NOM (celles à inclure).

L'instance table5 contient toutes les colonnes à l'exception de DATE_NAISSANCE (celle à exclure).

L'instance table6 contient uniquement NOM (ID était à inclure et à exclure).

Il est possible de consulter plus d'informations dans la documentation officielle de Table.

Un objet Request correspond tout simplement à une requête SQL dans la base de données. Sa construction nécessite au minimum un moyen de connexion à la base et le SQL de la requête.

// Les deux instanciations ci-dessous correspondent à des objets Request
// dans la base H2 en mémoire
// Instanciation d'un objet Request grâce à un objet DataSource
Request request1 = new Request(dataSource, 
                               "select * from membres where surnom is not null");
// Instanciation d'un objet Request grâce à un objet Source
Request request2 = new Request(source, 
                               "select * from membres where surnom is not null");

Cela donne la représentation suivante :

Le constructeur Request comporte également des paramètres optionnels qui sont utilisés comme paramètres pour l'exécution de la requête SQL.

// Instanciation d'un objet Request avec un paramètre
Request request3 = new Request(dataSource, 
                               "select nom nom_membre, prenom from membres where taille > ?", 
                               1.75);
// Instanciation d'un objet Request avec deux paramètres
Request request4 = new Request(source, 
                               "select nom, prenom, surnom from membres where taille > ? and prenom like ?", 
                               1.75, 
                               "?vid%");

L'instance request3 contient les enregistrements respectant la condition (une fois le paramètre de requêtes remplacé par 1.75) et les colonnes correspondent aux colonnes de la requête (en tenant compte des alias).

L'instance request4 fonctionne sur le même principe (il y a juste deux paramètres de requêtes au lieu d'un seul).

Il est possible de consulter plus d'informations dans la documentation officielle de Request.

Un objet Changes correspond aux changements de valeur des données durant un intervalle de temps défini par un point de début et un point de fin. Concrètement l'état des données à l'instant du point de début est comparé avec l'état des données du point de fin. Ces changements peuvent être sur une/des table(s) (seuls les changements de valeurs dans la/les table(s) sont pris en compte), une requête (seuls les changements de valeurs dans le résultat de la requête sont pris en compte) ou un moyen de connexion à la base de données (les changements de valeurs dans l'ensemble de la base de données sont pris en compte).

Voici l'état des tables au point de départ :

Entre le point de départ et le point de fin, les requêtes suivantes sont exécutées.

delete from appartenances where id_membre = 7;
delete from membres where id = 7;
insert into membres(id, nom, prenom, date_naissance) values(8, 'Summers', 'Andrew James', PARSEDATETIME('31/12/1942', 'dd/MM/yyyy'));
insert into appartenances values(1, 8);
update membres set surnom = 'Sting' where id = 5;

Voici donc l'état des tables au point de fin :

• la table GROUPES n'est pas modifiée :

  Table GROUPES
  ID	NOM
  1	The Police

• dans la table MEMBRES, l'enregistrement avec ID 5 est modifié (colonne SURNOM), l'enregistrement avec ID 7 est supprimé et l'enregistrement avec ID 8 est créé.

  Table MEMBRES
  ID	NOM	PRENOM	SURNOM	DATE_NAISSANCE	TAILLE
  5	Sumner	Gordon Matthew Thomas	Sting	02/10/1951	1,82
  6	Copeland	Stewart Armstrong		16/07/1952	1,87
  8	Summers	Andrew James		31/12/1942

• dans la table MEMBRES, l'enregistrement avec ID_GROUPE 1 et ID_MEMBRE 7 est supprimé et l'enregistrement avec ID_GROUPE 1 et ID_MEMBRE 8 est créé.

  private void faireChangements() throws SQLException {
    try (Connection connection = dataSource.getConnection()) {
      try (Statement statement = connection.createStatement()) {
        statement.executeUpdate("delete from appartenances where id_membre = 7;");
        statement.executeUpdate("delete from membres where id = 7;");
        statement.executeUpdate("insert into membres(id, nom, prenom, date_naissance) values(8, 'Summers', 'Andrew James', PARSEDATETIME('31/12/1942', 'dd/MM/yyyy'));");
        statement.executeUpdate("insert into appartenances values(1, 8);");
        statement.executeUpdate("update membres set surnom = 'Sting' where id = 5;");
      }
    }
  }

  @Test
  public void test() throws SQLException {
    Table table1 = new Table(dataSource, 
                             "MEMBRES");
    Changes changes1 = new Changes(table1);
    //Changements sur la table MEMBRES sans tenir compte de la colonne SURNOM
    Table table2 = new Table(dataSource, 
                             "MEMBRES", 
                             null, 
                             new String[] { "SURNOM" });
    Changes changes2 = new Changes(table2);
    // Changements dans le résultat d'une requête
    Request request1 = new Request(dataSource, 
                                   "select groupes.nom nom_groupe, " +
                                   "       membres.nom nom_membre, " +
                                   "       membres.surnom, " +
                                   "       membres.id id_membre " +
                                   " from membres, " +
                                   "      groupes, " +
                                   "      appartenances " +
                                   " where membres.id = appartenances.id_membre " +
                                   " and groupes.id = appartenances.id_groupe " +
                                   " and membres.taille is not null");
    Changes changes3 = new Changes(request1);
    // Changements dans le résultat d'une requête
    Request request2 = new Request(dataSource, 
                                   "select groupes.nom as nom_groupe, " +
                                   "       membres.nom nom_membre, " +
                                   "       membres.surnom, " +
                                   "       membres.id id_membre " +
                                   " from membres, " +
                                   "      groupes, " +
                                   "      appartenances " +
                                   " where membres.id = appartenances.id_membre " +
                                   " and groupes.id = appartenances.id_groupe " +
                                   " and membres.taille is not null");
    request2.setPksName("id_membre");
    Changes changes4 = new Changes(request2);
    // Changements sur l'ensemble de la base de données
    Changes changes5 = new Changes(dataSource);
    changes1.setStartPointNow();
    changes2.setStartPointNow();
    changes3.setStartPointNow();
    changes4.setStartPointNow();
    changes5.setStartPointNow();
    faireChangements();
    changes1.setEndPointNow();
    changes2.setEndPointNow();
    changes3.setEndPointNow();
    changes4.setEndPointNow();
    changes5.setEndPointNow();

    ...
  }

Les changements sont triés par type de changement (CREATION, MODIFICATION puis DELETION) puis par nom de table et par valeur de clé primaire (à défaut par valeur des colonnes en tenant compte de l'ordre des colonnes).

changes1 contient uniquement les changements dans la table MEMBRES.

changes2 contient les changements dans la table MEMBRES, mais pas la modification, car elle est sur la colonne SURNOM qui a été exclue de table2.

changes3 contient les changements dans la requête, mais la modification est considérée comme un effacement et une création (request1 n'a pas de clé primaire déclarée donc AssertJ-DB ne sait pas comment déterminer quels enregistrements sont les mêmes avec modification).

changes4 contient le changement dans la requête en tant que modification, car ID_MEMBRE a été déclaré comme clé primaire.

changes5 contient tous les changements qui se sont produits dans la base de données entre le point de début et le point de fin.

Il est possible de consulter plus d'informations dans la documentation officielle de Changes.

Un objet Change correspond à un changement parmi les changements d'un Changes.

L'objet Changes changes5 (présenté dans le chapitre II-B-3 précédent) contient 5 changements (Change).

Un Change contient les informations de type de changement, le nom de la table, la valeur de la clé primaire ainsi que les enregistrements au point de début et au point de fin.

Dans l'exemple ci-dessous, le changement sélectionné (en gras sur fond coloré) est le deuxième changement (Change) de changes5 ne contient pas d'enregistrement de début, car il s'agit d'une création.

Il est possible de consulter plus d'informations dans la documentation officielle de Change.

Un objet Row correspond à un enregistrement : un enregistrement dans une table, dans le résultat d'une requête ou l'enregistrement au point de début ou de fin d'un changement.

Dans l'exemple ci-dessous, l'enregistrement sélectionné (en gras sur fond coloré) est le troisième enregistrement (Row) de table4.

Dans l'exemple ci-dessous, l'enregistrement sélectionné (en gras sur fond coloré) est le premier enregistrement (Row) de request1.

Dans l'exemple ci-dessous, l'enregistrement sélectionné (en gras sur fond coloré) est l'enregistrement au point de fin (Row) du troisième changement de changes5.

Il est possible de consulter plus d'informations dans la documentation officielle de Row.

Un objet Column correspond à une colonne : une colonne dans une table, dans le résultat d'une requête ou dans un changement.

Dans l'exemple ci-dessous, la colonne sélectionnée (en gras sur fond coloré) est la première colonne (Column) de table4.

Dans l'exemple ci-dessous, la colonne sélectionnée (en gras sur fond coloré) est la troisième colonne (Column) de request1.

Dans l'exemple ci-dessous, la colonne sélectionnée (en gras sur fond coloré) est la cinquième colonne (Column) du troisième changement de changes5.

Il est possible de consulter plus d'informations dans la documentation officielle de Column.

Une valeur peut être obtenue depuis un objet Row ou un objet Column.

Dans l'exemple ci-dessous, la valeur sélectionnée (en gras sur fond coloré) est à la fois la première valeur du troisième enregistrement de table4 et la troisième valeur de la première colonne de table4.

Dans l'exemple ci-dessous, la valeur sélectionnée (en gras sur fond coloré) est à la fois la troisième valeur du premier enregistrement de request1 et la première valeur de la troisième colonne de request1.

Dans l'exemple ci-dessous, la valeur sélectionnée (en gras sur fond coloré) est à la fois la sixième valeur de l'enregistrement au point de fin du troisième changement de changes5 et la valeur au point de fin de la sixième colonne du troisième changement de changes5.

Il est possible de consulter plus d'informations dans la documentation officielle de Value.

Comme vu dans ce chapitre, les éléments Change, Row, Column et Value sont plus ou moins directement des sous-éléments de Table, Request et Changes.

Inversement, Table, Request et Changes sont des éléments racine. Cela signifie que les assertions auront toujours comme point de départ un de ces trois éléments.

Table et Request sont des éléments racine de données. Cela signifie que ces éléments ont des correspondances dans la base de données. Tandis que Changes correspondra à des changements dans une ou plusieurs Tables ou dans le résultat d'une Request.

Le type de données (DataType) est une information permettant de distinguer les deux types d'éléments de données :

• TABLE pour une table de données ;
• REQUEST pour le résultat d'une requête.

Il est possible de consulter plus d'informations dans la documentation officielle de DataType.

Le type de changement (ChangeType) est une information permettant de distinguer les trois types de changement sur les données correspondant aux trois opérations SQL de modification :

• CREATION pour une requête SQL insert;
• MODIFICATION pour une requête SQL update;
• DELETION pour une requête SQL delete.

Il est possible de consulter plus d'informations dans la documentation officielle de ChangeType.

Le type de valeur (ValueType) est une information permettant de distinguer les différents types de valeur correspondant aux différentes classes retournées lors de la récupération des données depuis la base de données :

• BYTES si JDBC retourne un tableau d'octets (byte[]) ;
• BOOLEAN si JDBC retourne un java.lang.Boolean ;
• TEXT si JDBC retourne un java.lang.String ;
• DATE si JDBC retourne un java.sql.Date ;
• TIME si JDBC retourne un java.sql.Time ;
• DATE_TIME si JDBC retourne un java.sql.Timestamp ;
• NUMBER si JDBC retourne un java.lang.Byte, java.lang.Short, java.lang.Integer, java.lang.Long, java.lang.Float ou java.math.BigDecimal ;
• NOT_IDENTIFIED pour les autres cas (par exemple si la valeur est null).

Il est possible de consulter plus d'informations dans la documentation officielle de ValueType.

Les éléments racine Table, Request et Changes sont les points de départ de toutes les assertions.

Une assertion commence toujours avec l'appel à la méthode statique assertThat(...). Cette méthode appartient à la classe Assertions.

Pour utiliser les assertions, il est pratique de procéder au départ à un import statique de cette méthode. Cela rendra l'écriture/lecture du code plus simple.

import static org.assertj.db.api.Assertions.assertThat;

Chaque élément racine a sa méthode assertThat(...) pour commencer l'assertion :

• avec un objet Table :

  assertThat avec un objet Table

  Sélectionnez

  assertThat(table)...       // L'assertion est pour le moment au niveau de la table

• avec un objet Request :

  assertThat avec un objet Request

  Sélectionnez

  assertThat(request)...   // L'assertion est pour le moment au niveau de la requête

• avec un objet Changes :

assertThat(changes)...   // L'assertion est pour le moment au niveau des changements

Il est possible de consulter plus d'informations dans la documentation officielle.

La navigation depuis une Table, ou une Request est similaire, car comme vu plus haut dans la présentation des éléments leur structure de sous-éléments est identique.

Les flèches continues en rouge représentent la navigation « descendante ».
Les flèches en pointillé en bleu représentent la navigation « remontante ».

Dans les sous-chapitres, nous utiliserons pour les exemples la table MEMBRES ci-dessous.

II-D-2-a. La navigation « descendante »▲

assertThat(table).row(2)...

assertThat(table).row(2).row()...

assertThat(table).row()...

assertThat(table).column("prenom")...

assertThat(table).column(1)...

assertThat(table).column()...

assertThat(table).row(2).value(2)...
assertThat(table).row(2).value("prenom")...
assertThat(table).row(2).value().value().value()...
assertThat(table).row(2).value(1).value()...

assertThat(table).column("prenom").value(2)...
assertThat(table).column(2).value(1).value()...
assertThat(table).column(2).value().value().value()...

II-D-2-b. La navigation « remontante »▲

assertThat(table).row(2).value(2).returnToRow()...
assertThat(request).row().value("prenom").returnToRow()...

assertThat(table).column("prenom").value(2).returnToColumn()...
assertThat(request).column(4).value(2).returnToColumn()...

assertThat(table).row(2).returnToTable()...
assertThat(table).column("prenom").returnToTable()...

assertThat(request).row().returnToRequest()...
assertThat(request).column(4).returnToRequest()...

Il est possible de consulter plus d'informations dans la documentation officielle.

Les flèches continues en rouge représentent la navigation « descendante ».
Les flèches en pointillé en bleu représentent la navigation « remontante ».

Dans les sous-chapitres, nous utiliserons pour les exemples les changements ci-dessous.

II-D-3-a. La navigation « descendante »▲

assertThat(changes).onTable("membres")...

assertThat(changes).ofCreation()...

assertThat(changes).ofCreationOnTable("membres")...

assertThat(changes).change(2)...

assertThat(changes).onTable("MEMBRES").change(1).change()...

assertThat(changes).changeOfCreation(1)...

assertThat(changes).changeOnTableWithPks("APPARTENANCES", 1, 7)...

assertThat(changes).onTable("MEMBRES").change(2).rowAtStartPoint()...

assertThat(changes).onTable("MEMBRES").change(2).rowAtEndPoint()...

assertThat(changes).change(3).column("prenom")...

// Les deux lignes sont équivalentes
assertThat(changes).change(3).columnAmongTheModifiedOnes()...
assertThat(changes).change(3).columnAmongTheModifiedOnes(0)...

assertThat(changes).change(3).rowAtStartPoint().value("prenom")...

assertThat(changes).change(3).column("prenom").valueAtStartPoint()...

II-D-3-b. La navigation « remontante »▲

assertThat(changes).change(3).rowAtStartPoint().value("prenom").returnToRow()...

assertThat(changes).change(3).column("prenom").valueAtStartPoint().returnToColumn()...

assertThat(changes).change(3).rowAtStartPoint().returnToChange()...
assertThat(changes).change(3).column("prenom").returnToChange()...

assertThat(changes).change(3).returnToChanges()...

assertThat(changes).onTable("membres").ofAll()...

Nous avons vu qu'il était possible d'enchaîner des méthodes de navigation.

assertThat(table).row(2).row()...

Ce principe d'enchaînement est déclinable de pratiquement toutes les manières.
Il faut juste garder à l'esprit que les méthodes sont en réalité exécutées au niveau élément supérieur (ici la navigation de la méthode row() s'effectue l'élément table).
On peut en déduire que la ligne de code précédente est équivalente à celle-ci (c'est juste que le returnToTable() est implicite).

assertThat(table).row(2).returnToTable().row()...

Sur le même principe, nous pouvons enchaîner les méthodes suivantes :

assertThat(changes)
    .ofDeletion()                     // vers le sous-ensemble des changements de type DELETION
        .change()                     // Premier changement du sous-ensemble
            .rowAtStartPoint()        // Enregistrement au point de départ de ce premier changement
        .change()                     // Changement suivant
            .column("prenom")         // Colonne PRENOM de ce changement 
                .valueAtStartPoint()  // Valeur au point de départ de cette colonne
            .rowAtEndPoint()          // Enregistrement au point de fin de l'enregistrement
        .changeOfModification()       // Premier changement de type MODIFICATION (un appel à .ofAll() juste avant est implicite)
        .changeOfCreation(1)          // Changement de type CREATION à l'index 1
        ...

Si elle peut dériver vers un enchaînement absurde, cette facilité de navigation permet surtout une grande liberté au testeur. Il suffit comme nous le verrons un peu plus loin d'insérer les bonnes assertions entre les méthodes de navigation.

Un objet DateValue représente une date. Il peut être instancié en utilisant les méthodes :

• of(...) :

  Instanciation avec des int en paramètres

  Sélectionnez

  DateValue dateValue = DateValue.of(2007, 12, 23);

• from(...) :

  Instanciation avec un java.sql.Date en paramètre

  Sélectionnez

  Date date = Date.valueOf("2007-12-23");
  DateValue dateValue = DateValue.from(date);

• parse(...) :

DateValue dateValue = DateValue.parse("2007-12-23");

Un objet TimeValue représente une heure. Il peut être instancié en utilisant les méthodes :

• of(...) :

  Instanciation avec des int en paramètres

  Sélectionnez

  // En indiquant juste les heures et minutes
  TimeValue timeValue1 = TimeValue.of(9, 1);
  // Avec les secondes en plus
  TimeValue timeValue2 = TimeValue.of(9, 1, 6);
  // Avec les nanosecondes en plus
  TimeValue timeValue3 = TimeValue.of(9, 1, 6, 3);

• from(...) :

  Instanciation avec un java.sql.Time en paramètre

  Sélectionnez

  Time time = Time.valueOf("09:01:06");
  TimeValue timeValue = TimeValue.from(time);

• parse(...) :

// En indiquant juste les heures et minutes
TimeValue timeValue1 = TimeValue.parse("09:01");
// Avec les secondes en plus
TimeValue timeValue2 = TimeValue.parse("09:01:06");
// Avec les nanosecondes en plus
TimeValue timeValue3 = TimeValue.parse("09:01:06.000000003");

Un objet DateTimeValue représente une date/heure. Il peut être instancié en utilisant les méthodes :

• of(...) :

  Instanciation avec un DateValue et un TimeValue en paramètres

  Sélectionnez

  // Avec la date seulement (l'heure est mise à minuit)
  DateTimeValue dateTimeValue1 = DateTimeValue.of(dateValue);
  // Avec la date et l'heure
  DateTimeValue dateTimeValue2 = DateTimeValue.of(dateValue, timeValue1);

• from(...) :

  Instanciation avec un java.sql.Timestamp en paramètre

  Sélectionnez

  Timestamp timestamp = Timestamp.valueOf("2007-12-23 09:01:06.000000003");
  DateTimeValue dateTimeValue = DateTimeValue.from(timestamp);

• parse(...) :

// Avec la date seulement (l'heure est mise à minuit)
DateTimeValue dateTimeValue1 = DateTimeValue.parse("2007-12-23");
// Avec la date et l'heure (en indiquant juste les heures et minutes)
DateTimeValue dateTimeValue2 = DateTimeValue.parse("2007-12-23T09:01");
// Avec la date et l'heure (avec les secondes en plus)
DateTimeValue dateTimeValue2 = DateTimeValue.parse("2007-12-23T09:01:06");
// Avec la date et l'heure (avec les nanosecondes en plus)
DateTimeValue dateTimeValue2 = DateTimeValue.parse("2007-12-23T09:01:06.000000003");