Skip to content

XForm-test is a tool for creating and running tests to ensure the quality and stability of XForms.

License

Notifications You must be signed in to change notification settings

PMA-2020/xform-test

Repository files navigation

XFormTest

XFormTest is a tool for creating and running tests to ensure the quality and stability of XForms.

Quick start

  1. Prerequisites: i. Java 8, ii. access to an XLSForm (excel) to XForm (xml) converter, such as pyxform or XLSForm online, or XLSForm offline.
  2. Download XFormTest.
  3. Download this example XLSForm and convert it to XML.
  4. Run the pre-made tests in the example form (replace "x.y.z" with the version number in the file name of the Java jar file downloaded): java -jar xform-test-x.y.z.jar xlsxExample.xml

Quick start video: https://www.youtube.com/watch?v=doAr26GaTSQ

Installation

XFormTest does not need to be installed. You simply have to have Java 8 in order to run it.

Pre-requisities

Download

You can download XFormTest from the GitHub release page.

Basic Usage

Command syntax

java -jar path/to/xform-test-x.y.z.jar path/to/someFile.xml

Example usage

If you've downloaded version 0.1.0 of XFormTest and an XForm XML file called "someFile.xml", and both of these are in the same folder, you would open up your terminal at that folder and run the following command: java -jar xform-test-0.1.0.jar someFile.xml

Creating tests

XFormTest introduces a concept we call the "linear scenario test". A linear scenario test defined as a set of assertions to be executed in a sequence, one after the other.

XLSForm setup

For a quick idea of how this works in an XLSForm, check out the example below. There's also a demo form available for download here.

xlsx_example.png An example XLSForm with tests.

Adding the XFormTest column

XFormTest utilizes special columns for linear assertion. Any of the following 3 column names are valid.

  • bind::xform-test-linearAssert
  • bind::xform-test
  • bind::test

Any text entered into the cells of this column are considered "assertions". An "assertion" represents something about the particular question or prompt that you expect to be true. In the context of a linear scenario test, the assertion states something expected to be true not just in isolation, but also true following every other assertion made in the form up to that point.

Adding assertions

There are 2 types of assertions: value assertions, and relevant assertions.

Value assertions indicate that the user is able to enter the given specified value for a given question. In a future release of XFormTest, we are also planning to allow assertions on calculates.

Relevant assertions allow you to simply assert whether a given question/prompt is relevant or not.

Assertion type XLSForm examples XForm example
Value Bob or value: Bob <bind ... xform-test-linearAssert="Bob"/>
Relevant relevant: 0 <bind ... xform-test-linearAssert="relevant: 0"/>

Multiple tests in a single form

Support for multiple linear scenario tests (e.g. multiple columns in a single XLSForm) is not currently available, but planned to be implemented in a future release.

Syntax reference

Expressions

[nodeset attribute-1]: [nodeset attribute-1-evaluated-value], ...

Quick example: relevant: 1, value: yes, constraint: 0

Assertion types

Value

A value assertion is the assertion that some value can be entered for a given question / node. The data type for a value assertion depends on the question / node type. A text type would accept string values, an integer type would accept integer values, a calculate type could accept any kind of data value, and so on.

For example, for a quesiton such as "How many days a week is this facility open?", one might want to value assertion of a number 1 through 7.

Relevant

A relevant assertion is an assertion on the evaluation of an expression set on the relevant attribute of a given question / node. It accepts a boolean of one of the following forms: false, true, 0 or 1.

For example, if there are a particular question has complex pre-conditions, one might want to create a linear scenario test where, after these pre-conditions are met, the relevant of the questions hould evaluate to 1.

Miscellaneous

Useful resources

General resources

Other XML and XForm based testing projects

  • XMLUnit - An XML language native, platform agnostic library for comparing XML documents, schema validation, and XPath value assertion
  • XForms Unit - a non-implemented unit testing library specification
  • Orbeon Testsuite - A selenium-based test runner specifically for Orbeon
  • XForms Client-Side Unit Tests - Another Orbeon-specific test suite for unit tests implemented in JavaScript

Giving feedback or reporting bugs

Send an e-mail to jflack@jhu.edu, or, even better, write an issue on GitHub.

Collaboration

XForm-test is forkable. Pull requests welcome!

Getting help

Send an e-mail to jflack@jhu.edu or write an issue on GitHub. For now, live, real time assistance is also available on Skype. Send a message to: joeflack4.


XFormTest

XFormTest est un outil permettant de créer et d’exécuter des tests pour assurer la qualité et stabilité des XForms.

Démarrage rapide

  1. Prérequis : i. Java 8, ii. Accès à un convertisseur de XLSForm (Excel) vers XForm (xml), comme par exemple pyxform ou XLSForm online, ou encore XLSForm offline.
  2. Télécharger XFormTest.
  3. Télécharger cet exemple XLSForm et convertissez-le en XML.
  4. Exécutez les tests pré-créés dans l’exemple de formulaire (remplacez "x.y.z" par le numéro de version dans le nom du fichier Java jar téléchargé) : java -jar xform-test-x.y.z.jar xlsxExample.xml

Vidéo : https://www.youtube.com/watch?v=doAr26GaTSQ

Installation

XFormTest n’a pas besoin d’être installé. Vous devrez simplement avoir Java 8 pour l’exécuter.

Prérequis

Téléchargement

Vous pouvez télécharger XFormTest sur page de publication de GitHub.

Usage de base

Syntaxe de commande

java -jar path/to/xform-test-x.y.z.jar path/to/someFile.xml

Exemple d’usage

Si vous avez téléchargé la version 0.1.0 de XFormTest et le fichier XForm XML appelé "someFile.xml", et que les deux se trouvent dans le même dossier, vous devrez ouvrir votre terminal pour ce dossier et exécuter la commande suivante : java -jar xform-test-0.1.0.jar someFile.xml

Créer des tests

XFormTest introduit un concept que nous appelons le « test du scénario linéaire » (« linear scneario test », en anglais). Un linear scenario test est défini comme un ensemble d’assertions à exécuter par séquence, l’une après l’autre.

Paramétrage de XLSForm

Pour savoir rapidement en quoi cela consiste dans un XLSForm, référez-vous à l’exemple ci-dessous. Une démo est aussi disponible en téléchargement ici.

xlsx_example.png Un exemple de XLSForm avec des tests.

Ajouter des colonnes dans XFormTest

XFormTest utilise des colonnes spéciales pour des assertions linéaires. Les 3 noms de colonnes suivants sont tous valides.

  • bind::xform-test-linearAssert
  • bind::xform-test
  • bind::test

Tout texte saisi dans les cellules de cette colonne sont considérés comme des "assertions". Une "assertion" représente ce que vous attendez d’une question ou relance comme étant vrai. Dans le contexte d’un test de scénario linéaire, l’assertion établit quelque chose qui devrait être vrai, pas simplement de manière isolée, mais aussi en suivant toutes les autres assertions apportées au formulaire jusqu’à présent.

Ajouter des assertions

Il y a 2 types d’assertions : value assertions, et relevant assertions.

Value assertions indique que l’utilisateur est en mesure de saisir une valeur spécifique pour une question donnée. Dans la prochaine version du XFormTest, nous prévoyons de permettre des assertions sur des calculs également.

Relevant assertions vous permet d’affirmer simplement si une question/relance est pertinente ou non.

Type d’assertion Exemple de XLSForm Exemple de XForm
Valeur Bob ou value: Bob <bind ... xform-test-linearAssert="Bob"/>
Relevant relevant: 0 <bind ... xform-test-linearAssert="relevant: 0"/>

Tests multiples dans un seul formulaire

Les tests de scénarios linéaires multiples (ex : plusieurs colonnes dans un seul XLSForm) ne sont pas disponibles actuellement, mais prévus pour de prochaines versions.

Syntaxe de référence

Expressions

[nodeset attribute-1]: [nodeset attribute-1-evaluated-value], ...

Exemple : relevant: 1, value: oui, constraint: 0

Types d’assertion

Value

Une assertion value (de valeur) est l’assertion selon laquelle une certaine value peut être saisie pour une question donnée. Le type de donnée pour une assertion value dépend du type de question/ node. Un type text n’accepterait que des valeurs de caractères, et un type integer n’accepterait que des valeurs numériques, tandis qu’un type calculate pourrait accepter tout type de valeur de données, et ainsi de suite.

Par exemple, pour une question telle que « Combien de jours par semaine cette structure sanitaire est-elle ouverte ? », on pourrait avoir l’assertion de valeur du chiffre 1 à 7.

Relevant

Une assertion relevant (pertinente) est une assertion d’évaluation d’un ensemble d’expressions comme était relevant pour une question/node. Elle accepte un Boolean sous l’une des formes suivantes : false, true, 0 or 1.

Par exemple, si une question en particulier a des préconditions complexes, on pourrait vouloir créer un test de scénario linéaire selon lequel, une fois les préconditions remplies, l’assertion relevant des questions devrait être évaluée à 1.

Autres

Ressources utiles

Ressources générales

  • Documentation sur XForm Test
  • XForm Test sur GitHub
  • Open Data Kit – Une plateforme de collecte de données en accès libre utilisant XForms.
  • PMA – Une organisation programmatique de collecte de données pour des enquêtes permettant de générer rapidement des résultats afin de surveiller des indicateurs clés de santé et de développement. Lieu de naissance de XForm Test.
  • PMA sur GitHub – Projets et initiatives de PMA en accès libre.

**Autres projets de tests basés sur XML et XForm **

  • XMLUnit - Langue native XML, plateforme et répertoire agnostiques permettant la comparaison des documents XML, validation de schémas, et assertion de valeur XPath
  • XForms Unit – Un répertoire de tests unitaires non appliqués
  • Orbeon Testsuite – Permet d’exécuter les tests basés sur selenium spécifiquement pour Orbeon
  • XForms Client-Side Unit Tests – Une autre suite de tests propre à Orbeon pour les tests unitaires exécutés sous JavaScript

Rapporter des anomalies

Envoyez un email à jflack@jhu.edu, ou mieux encore, postez votre problème sur GitHub.

Collaborer

XForm-test peut être « forké » sur GitHub. Les « Pull requests » sont bienvenues !

Obtenir de l’aide

Envoyez un email à jflack@jhu.edu ou postez votre problème sur GitHub. Pour le moment, vous pouvez obtenir de l’aide en temps réel sur Skype. Envoyez un message à : joeflack4.

About

XForm-test is a tool for creating and running tests to ensure the quality and stability of XForms.

Resources

License

Stars

Watchers

Forks

Packages

No packages published