Package caseine.tags

Annotation Interface ToCompare

@Retention(RUNTIME) @Target(METHOD) public @interface ToCompare
Pour vérifier que la méthode annotée est fonctionnellement équivalente à une méthode de référence sur la base de liste de jeux de tests.
Author:
Yvan Maillot <yvan.maillot@uha.fr>

L'annotation @caseine.tags.ToCompare

Le principe consiste à comparer le résultat de la méthode de l'étudiant avec celui de la méthode de la correction (de l'enseignant),

  1. soit à partir de jeux de tests calculés aléatoirement.
  2. soit à partir de jeux de tests choisis par l'enseignant.

Attention: la première solution est facile à utiliser et commode mais aussi très limitée. D'une part, il est nécessaire que les paramètres de la méthode ainsi que les attribut de l'objet sur lequel elle s'applique soient de type primitif. D'autre part, les jeux de tests générés ne sont pas toujours pertinents.

Attention: la deuxième est plus compliquée à mettre en place mais pratiquement sans limite.

Cible

@ToCompare ne s'applique qu'aux méthodes.

Formes d'emploi

@ToCompare s'emploi comme

  1. une annotation multivaluée (@ToCompare(priority = 1, grade = 1))

    Les propriétés possibles son :

    • value de type String : le message à afficher en cas d'échec de l'évaluation.
      Par défaut, un message standard est proposé.
    • priority de int : le numéro d'ordre (croissant) de traitement de l'évaluation.
      Par défaut, 0.
    • grade de type double : la valeur donnée de réussite de l'évaluation (avant un éventuel ajustement avec null @RelativeEvaluation).
      Par défaut, Double.MIN_VALUE
    • testSetsMethodName de type String :
      • Si elle n'est pas renseignée (ou égale à ""), les jeux de tests sont générés aléatoirement. Dans ce cas, attention aux limitations.
      • Sinon, elle doit représenter le nom pleinement qualifiée d'une méthode (à écrire par l'enseignant) qui retourne une liste de jeux de tests à employer pour l'évaluation.
      Par défaut "" (i.e. elle n'est pas renseignée).
    • numberOfAleaTestSets de type int : cette propriété n'est utile que si testSetsMethodName n'est pas renseignée. Elle définit le nombre de jeux de tests aléatoire générés.
      Par défaut 100.
    • checkStdOut de type boolean : l'évaluation tient compte de la sortie standard (affichage à l'écran) si true.
      Par défaut false.
    • inputString de type String : le flux d'entrée attendu par la méthode à évaluer (quand celle-ci lit des données au clavier).
      Par défaut "".
    • requiersUnitTestsBefore de type String[] : permet de s'assurer que des conditions préalables soient satisfaits avant de lancer cette évaluation.
      Par défaut {}.
    • comparatorMethodName de type String : cette propriété n'est utile que si testSetsMethodName est (correctement) renseignée. Dans ce cas, elle doit représenter le nom pleinement qualifiée d'une méthode (à écrire par l'enseignant) qui définit la comparaison.
      Par défaut "".
  2. une annotation monovaluée (@ToCompare("consigne")) ou "consigne" est une consigne à l'étudiant en cas d'échec de l'évaluation.
  3. une annotation de marquage (@ToCompare) Un message standard sera donné à l'étudiant en cas d'échec de l'évaluation. Pour le reste des propriétés et les effets, voir les valeurs par défaut des propriétés et les explications dans la suite.

De nombreuses explications complémentaires sont données dans la suite. À lire attentivement si l'on utilise les propriétés testSetsMethodName ou comparatorMethodName

Effets

L'annotation @ToCompare a pour effet de générer une évaluation qui compare le résultat de la méthode de l'étudiant avec celui de la méthode de référence à partir de jeux de tests générés au hasard ou choisis par l'enseignant.

La suite l'explique en détail.

Utilisation de la propriété testSetsMethodName

Cette propriété est une chaîne de caractères (String) qui représente le nom pleinement qualifié d'une méthode. Laquelle est chargée de retourner une liste de jeux de tests qui seront employés lors de l'évaluation. Elle doit satisfaire les conditions suivantes :

Par exemple,

testSetsMethodName = "edu.uha.miage.AClassTest.testSetsForAMethod"

signifie que les jeux de tests sont issus de la méthode

public static List<InstanceAndParameters> testSetsForAMethod()

de la classe AClassTest.

Utilisation de la propriété comparatorMethodName

Cette propriété est une chaîne de caractères (String) qui représente le nom pleinement qualifié d'une méthode qui retourne une chaîne de caractères et reçoit en paramètre un objet contenant le nécessaire pour faire les comparaisons.

Elle doit satisfaire les conditions suivantes :

  • être accessible, i.e. publique et dans une classe publique (en général, on choisit une classe tests unitaires),
  • être déclarée static,
  • prendre un seul paramètre de type ToCompareProducer.ResultForComparison,
  • retourner une chaîne de caractère.

Par exemple,

comparatorMethodName = "edu.uha.miage.AClassTest.aMethodComparator"

représente la méthode

public static String aMethodComparator(caseine.publication.producers.ToCompareProducer.ResultForComparison rfc)

de la classe AClassTest.

La propriété comparatorMethodName doit nécessairement s'utiliser conjointement avec la propriété testSetsMethodName.

L'enseignant doit écrire comparatorMethodName de sorte qu'elle retourne
  1. "OK" si la comparaison à l'aide des données fournies par le paramètre ResultForComparison est satisfaisante,
  2. ou autre chose dans le cas contraire. Cet autre chose peut être un message destiné à l'étudiant dont le contenu est laissé à l'appréciation de l'enseignant.
Voir ResultForComparison est documentée dans la suite.

Utilisation de la propriété requiersUnitTestsBefore

Cette propriété est un tableau de chaînes de caractères (String[]) dont chaque élément doit être :

  1. soit une chaîne de caractères convertible en entier (e.g. "2").
    Dans ce cas, cela signifie que toutes les évaluations automatiques de priorité égale à cet entier converti (e.g. toutes les évaluations de priorité 2) doivent réussir pour que celle-ci réussisse.
  2. soit une chaîne de caractères qui représente le nom pleinement qualifié d'un test unitaire accessible existant ou écrit par l'enseignant (e.g. "edu.uha.miage.PointTest.checkOrigine").
    Dans ce cas, cela signifie que la méthode de test unitaire (e.g. "public void checkOrigine()" de la classe "public void edu.uha.miage.PointTest") doit réussir pour que cette évaluation réussisse.

Attention aux dépendances cycliques.

See Also:

  • Element Details

    • value

      String value
      Définit la consigne destinée à l'étudiant quand le test échoue.
      Quand la valeur par défaut est choisie, un message standard est généré.
      Returns:
      la consigne destinée à l'étudiant.
      Default:
      ""

    • priority

      int priority
      définit l'ordre de priorité croissante du test généré dans sa classe de tests unitaires
      Returns:
      l'ordre de priorité.
      Default:
      0

    • grade

      double grade
      définit le nombre de points attribués à la réussite de ce test ou une valeur relative si le tag RelativeEvaluation est employé.

      Un grade négatif ou nul est ignoré.

      Returns:
      le grade.
      See Also:
      Default:
      4.9E-324

    • testSetsMethodName

      String testSetsMethodName
      Default:
      ""

    • checkStdOut

      boolean checkStdOut
      Default:
      false

    • comparatorMethodName

      String comparatorMethodName
      Default:
      ""

    • numberOfAleaTestSets

      int numberOfAleaTestSets
      Default:
      100

    • inputString

      String inputString
      Default:
      ""

    • requiersUnitTestsBefore

      String[] requiersUnitTestsBefore
      définit un tableau de chaînes de caractères qui représentent des tests unitaires.

      Chaque chaîne de ce tableau peut être

      • Soit convertible en entier, dans ce cas, elle représente tous des tests unitaires de cette priorité.
      • Soit le nom pleinement qualifié d'une méthode de test unitaire.

      Pour que le test unitaire annoté réussisse, il faut que tous les tests unitaires représentés dans ce tableau réussissent.

      Attention aux dépendances cycliques

      Returns:
      le tableau des tests unitaires
      Default:
      {}