Faire valider son travail avec dsoxlab check et submit

dsoxlab check joue les tests du lab, calcule la note, l'enregistre et affiche un état par critère : satisfait, non satisfait, non évalué ou sauté. Ce qu'il dit d'un critère raté dépend du type du lab : le message complet de l'auteur sur un lab guidé, un indice court sur un challenge, le verdict seul sur une épreuve (un lab qui fixe un seuil de réussite). Cette leçon s'adresse à qui joue déjà des labs et veut savoir lire un résultat sans deviner. Elle compare check et submit, explique ce que juge une épreuve, et montre comment lire l'état d'un lab avec status.

Ce que vous allez apprendre

• Lire un résultat de dsoxlab check critère par critère.
• Distinguer un critère non satisfait d'un critère non évalué, qui n'est pas votre faute.
• Savoir ce que check montre d'un échec sur un lab guidé, un challenge et une épreuve.
• Comparer check et submit, et lire le verdict d'une épreuve.
• Lire l'état d'un lab avec dsoxlab status.

Prérequis

Il vous faut la CLI dsoxlab en version 0.8.0 ou plus récente, un lab démarré comme le décrit la leçon Démarrer un lab, et l'habitude de la boucle montrée par la leçon Jouer son premier lab.

Que fait dsoxlab check, et que change dsoxlab submit ?

dsoxlab check <id> exécute les tests du lab, calcule la note en y déduisant le coût des indices, l'enregistre, et affiche le détail de chaque critère. Vous pouvez le relancer autant de fois que vous voulez : chaque passage enregistre une tentative, tentatives ratées comprises, et la meilleure devient le score que show et list-labs affichent.

Le score est la proportion de tests réussis appliquée à un barème de 100 points diminué du coût des indices pris, et il ne descend jamais sous zéro.

dsoxlab check l2-swap-management
dsoxlab check drill-storage --target ubuntu   # lab multi-hôtes du catalogue linux : on teste la cible ubuntu
dsoxlab submit l2-swap-management             # même validation, puis clore la session

dsoxlab submit fait la même validation puis clôt la session : dans le sous-shell ouvert par run, il faut ensuite taper exit, et submit vide aussi le lab actif. Sur un lab ordinaire, c'est la seule différence : on joue check tant qu'on corrige, et submit quand on a fini. Sur un lab qui déclare un seuil de réussite, une épreuve, submit rend en plus un verdict.

Les codes de sortie de check disent la même chose que l'écran. Il sort en 1 quand un test échoue, ce qui concerne votre travail, et en 2 quand l'infrastructure d'un lab vm n'est pas provisionnée, ce qui concerne votre installation et n'enregistre rien.

Comment lire le résultat de check, critère par critère ?

Chaque test devient un critère, et un critère a quatre états : satisfait, non satisfait, non évalué ou sauté. Chacun se lit à l'écran pendant l'exécution, et un résumé « Ce qui reste à faire » suit dès qu'un critère n'est pas satisfait. Voici un premier check, joué avec la 0.8.0 sur le lab docker-premier-conteneur juste après dsoxlab run, avant d'avoir rien fait :

$ dsoxlab check docker-premier-conteneur
ℹ Validation de docker-premier-conteneur…
  ✘ test_functional.py::test_un_conteneur_a_ete_lance_et_tourne  (FAILED)
  ⊘ test_functional.py::test_les_journaux_du_conteneur_portent_la_ligne_demandee
(skipped)
  ✘ test_functional.py::test_le_conteneur_en_service_a_ete_arrete  (FAILED)
  ✘ test_functional.py::test_le_conteneur_au_rebut_a_ete_supprime  (FAILED)
  Tests docker-premier-conteneur terminés ━━━━━━━━━━━━━━━━━━━━━━━━━━ 4/4 0:00:01
Ce qui reste à faire, d'après les tests :
  ✘ un conteneur a ete lance et tourne
      aucun conteneur nommé `premier` n'existe. L'image `lab-base:1.0` est déjà
      sur la machine : rien à tirer, rien à construire.
      conteneurs présents : rebut, vitrine
  ✘ le conteneur en service a ete arrete
      `vitrine` tourne toujours. L'arrêter met fin à son processus tout en
      conservant le conteneur, ses journaux et son nom.
  ✘ le conteneur au rebut a ete supprime
      `rebut` existe toujours (état : exited). Arrêter un conteneur ne le
      supprime pas : tant qu'il existe, il garde son nom, et aucun autre
      conteneur ne peut le reprendre.
ℹ La sortie complète des tests : dsoxlab -v check docker-premier-conteneur
╭─ Résultat : docker-premier-conteneur ─╮
│  0 / 100 pts                          │
│  ░░░░░░░░░░░░░░░░░░░░  0/4 tests      │
╰───────────────────────────────────────╯
ℹ Résultat enregistré dans l'historique (0/100 pts).
✘ Des tests ont échoué.

Regardez d'abord les quatre lignes du haut : une coche pour un critère satisfait, une croix pour un critère non satisfait, et ⊘ pour un test sauté. Le test des journaux est sauté parce qu'il suppose le conteneur premier, qui n'existe pas encore : le test commence par chercher ce conteneur et se saute s'il est absent (c'est le skip du fichier test_functional.py du catalogue). Un test sauté n'est ni réussi ni raté, et le critère n'apparaît pas dans « Ce qui reste à faire ».

Il compte pourtant pour zéro dans la note : dsoxlab check docker-premier-conteneur --json renvoie skipped: 1 et score: 0 sur ce lab frais, et la commande sort en code 1.

Regardez ensuite les trois blocs du bas : chaque critère non satisfait porte le message de l'auteur, qui dit ce que le test a constaté et pas seulement qu'il a échoué. Enfin, la ligne Résultat enregistré dans l'historique (0/100 pts) confirme qu'un résultat nul est enregistré lui aussi.

Après avoir lancé le conteneur premier (qui affiche premier-est-la) et arrêté vitrine, sans supprimer rebut, le second passage donne ceci :

$ dsoxlab check docker-premier-conteneur
ℹ Validation de docker-premier-conteneur…
  ✔ test_functional.py::test_un_conteneur_a_ete_lance_et_tourne
  ✔ test_functional.py::test_les_journaux_du_conteneur_portent_la_ligne_demandee
  ✔ test_functional.py::test_le_conteneur_en_service_a_ete_arrete
  ✘ test_functional.py::test_le_conteneur_au_rebut_a_ete_supprime  (FAILED)
  Tests docker-premier-conteneur terminés ━━━━━━━━━━━━━━━━━━━━━━━━━━ 4/4 0:00:01
Ce qui reste à faire, d'après les tests :
  ✘ le conteneur au rebut a ete supprime
      `rebut` existe toujours (état : exited). Arrêter un conteneur ne le
      supprime pas : tant qu'il existe, il garde son nom, et aucun autre
      conteneur ne peut le reprendre.
ℹ La sortie complète des tests : dsoxlab -v check docker-premier-conteneur
╭─ Résultat : docker-premier-conteneur ─╮
│  75 / 100 pts                         │
│  ███████████████░░░░░  3/4 tests      │
╰───────────────────────────────────────╯
ℹ Résultat enregistré dans l'historique (75/100 pts).
✘ Des tests ont échoué.

Le test des journaux est passé de sauté à satisfait dès que premier existe, et il ne reste qu'un critère à corriger. Le score vaut 75, soit trois tests sur quatre sur un barème de 100, sans indice, et check sort encore en code 1 tant qu'un test échoue. Quand les quatre critères seront satisfaits, la dernière ligne deviendra « Tous les tests sont passés ».

Le quatrième état se lit différemment. Un critère est non évalué quand le dispositif n'a pas pu le vérifier : une erreur de préparation d'un test (une fixture, c'est-à-dire la mise en place que le test attend) ou une erreur de collecte. Pendant l'exécution, la ligne porte (ERROR). Dans « Ce qui reste à faire », il s'affiche avec un point d'interrogation et la mention « non évalué : vérification impossible ». Ce n'est pas une faute de votre part : rien n'a été mesuré sur ce critère. Une pratique raisonnable est de relancer check, puis, si l'erreur revient, de lancer dsoxlab doctor et de signaler le problème avec dsoxlab support.

État	Ce que vous voyez	Qui est concerné
Satisfait	une coche verte	votre travail est conforme sur ce critère
Non satisfait	une croix, puis « non satisfait » dans le résumé	votre travail est à corriger
Non évalué	(ERROR) pendant l'exécution, puis un point d'interrogation et « non évalué : vérification impossible »	le dispositif, pas vous
Sauté	⊘ et (skipped), absent du résumé	le test suppose une condition absente

Glissez pour voir

Une dernière situation n'est ni un échec ni un succès : rien n'a été mesuré. check l'indique, sort en code 1 et n'inscrit aucune tentative, donc aucune note. Ce n'est pas un exercice raté, et les deux cas qui y mènent n'ont pas la même cause.

Si aucun test n'a pu être collecté, pytest n'a pas pu démarrer : un conftest.py qui lève, une machine injoignable ou une dépendance absente. La sortie juste au-dessus du message dit laquelle.

Si tous les tests ont été sautés, le lab n'est pas prêt : son répertoire de travail n'a pas été préparé, ou un service dont il a besoin ne tourne pas. check le dit et donne la commande à lancer d'abord, dsoxlab run <id>.

Que montre check d'un critère raté, selon le type de lab ?

Le type du lab règle ce que check dévoile d'un critère raté : tout sur un lab guidé, un indice court sur un challenge, rien d'autre que le verdict sur une épreuve. Ce choix protège la valeur de l'exercice. Un lab guidé enseigne, il peut tout dire. Un challenge ne doit pas rendre la solution avec l'énoncé de l'échec. Une épreuve mesure, et ne donne rien.

Type de lab	Ce que check montre d'un critère raté	Avec dsoxlab -v check
Lab guidé (lab)	Le message complet de l'auteur	La sortie complète des tests
Challenge	Le libellé du critère, son verdict et la première ligne du message de l'auteur	La sortie complète des tests
Épreuve (capstone, ou tout lab, challenge compris, qui déclare un seuil de réussite)	Le libellé du critère et son verdict, aucun message	Rien de plus : le détail n'est pas disponible

Glissez pour voir

Sur un challenge, la première ligne dit où chercher et les suivantes, qui portent le geste de réparation, ne sont pas montrées. Sur une épreuve, même dsoxlab -v check n'affiche pas la sortie brute des tests : seul le verdict par critère s'affiche, suivi d'une ligne qui dit que le détail n'est pas disponible. Voici un check joué sur l'épreuve epreuve-livrer-une-image du catalogue containers, sans avoir rien fait, après avoir pris deux indices :

$ dsoxlab check epreuve-livrer-une-image
ℹ Validation de epreuve-livrer-une-image…
  ✘ test_functional.py::test_la_livraison_est_publiee_et_designee_par_son_digest
(FAILED)
  ✘ test_functional.py::test_le_secret_a_servi_et_ne_survit_dans_aucune_couche
(FAILED)
  ✘ test_functional.py::test_le_client_nu_tire_par_digest_et_execute  (FAILED)
  ✘ test_functional.py::test_le_compte_en_lecture_seule_ne_peut_pas_publier
(FAILED)
  Tests epreuve-livrer-une-image terminés ━━━━━━━━━━━━━━━━━━━━━━━━━━ 4/4 0:00:02
Ce qui reste à faire, d'après les tests :
  ✘ La livraison est publiée et un client nu la récupère et l'exécute (non
satisfait)
  ✘ Le secret de construction a servi sans laisser de trace dans l'image (non
satisfait)
  ✘ Un compte en lecture seule ne peut pas publier dans le registre (non
satisfait)
╭─ Résultat : epreuve-livrer-une-image ─╮
│  0 / 100 pts                          │
│  ░░░░░░░░░░░░░░░░░░░░  0/4 tests      │
│  2 indices utilisés, -25 pts          │
╰───────────────────────────────────────╯
ℹ Résultat enregistré dans l'historique (0/100 pts).
✘ Des tests ont échoué.

Regardez la liste « Ce qui reste à faire » : chaque critère porte son libellé et « non satisfait », sans aucun message d'aide. Elle compte trois critères alors que quatre tests ont tourné : un critère peut regrouper plusieurs tests, et le premier libellé parle à la fois de publication et de reprise par le client nu. Le panneau rappelle les deux indices pris, qui retirent 25 points du barème. La commande est sortie en code 1.

Avec dsoxlab -v check, la sortie est la même, mais une ligne s'ajoute après la liste pour dire que le détail n'est pas disponible :

$ dsoxlab -v check epreuve-livrer-une-image
[...]
  ✘ Un compte en lecture seule ne peut pas publier dans le registre (non
satisfait)
ℹ C'est une épreuve : le détail des tests n'est pas disponible, seul le verdict
par critère l'est.
[...]

L'option -v est globale : elle se place avant le nom de la commande. Tapée après, elle est refusée :

$ dsoxlab check epreuve-livrer-une-image -v
Usage: dsoxlab check [OPTIONS] [lab_id]
Try 'dsoxlab check --help' for help.
╭─ Error ──────────────────────────────────────────────────────────────────────╮
│ No such option: -v                                                           │
╰──────────────────────────────────────────────────────────────────────────────╯

Le code de sortie est 2, une erreur d'usage. La forme valide reste dsoxlab -v check <lab>.

Le mode machine, dsoxlab check --json, suit la même règle. Il renvoie, en plus du score, failed_checks et criteria, et sur une épreuve son champ output est vide et output_withheld vaut true. Un script ne peut donc pas contourner la politique du lab en lisant le document JSON. Voici le document d'un check --json raté sur epreuve-livrer-une-image, abrégé aux champs qui servent à un script :

$ dsoxlab check epreuve-livrer-une-image --json
{
  "schema": 1,
  "lab": {
    "id": "epreuve-livrer-une-image",
    "type": "challenge",
    "exam_passing_score": 75,
    [...]
  },
  "check": {
    "ok": false,
    "passed": 0,
    "total": 4,
    "score": 0,
    "max_score": 100,
    "recorded": true,
    "status": "failed",
    "output": "",
    "output_withheld": true,
    "failed_checks": [
      "test_la_livraison_est_publiee_et_designee_par_son_digest",
      [...]
    ],
    "criteria": [
      {
        "id": "livraison-utilisable",
        "state": "unsatisfied",
        [...]
      },
      [...]
    ]
  }
}

Regardez output et output_withheld : la sortie brute est vide et le drapeau dit pourquoi. Le verdict se lit dans criteria, où state vaut ici unsatisfied, un jeton stable qui ne dépend pas de la langue. Le champ type vaut challenge : c'est ainsi que cette épreuve se déclare dans son lab.yaml, et c'est son exam_passing_score qui en fait une épreuve. La commande est sortie en code 1.

Le niveau de détail est celui que l'auteur du catalogue déclare avec le champ feedback: du lab.yaml (full, first-line ou verdict). Lui seul peut en dévoiler davantage sur une épreuve, jamais l'apprenant.

Comment une épreuve est-elle jugée ?

Une épreuve est un lab qui déclare un seuil de réussite, et submit en rend le verdict : réussie ou refusée, exprimé en pourcentage du barème. Les messages de la CLI disent tantôt « épreuve », tantôt « examen » : « Examen réussi », « Examen échoué » et « Épreuve refusée » concluent tous les trois une épreuve. Une épreuve peut aussi déclarer des contrôles bloquants, des critères dont l'échec suffit à refuser l'épreuve quel que soit le total. Voici la fin d'un submit sur epreuve-livrer-une-image, soumise sans rien avoir fait, avec un seuil de 75 % (le début de la sortie répète celle d'un check, il est abrégé) :

$ dsoxlab submit epreuve-livrer-une-image
[...]
╭─ Résultat : epreuve-livrer-une-image ─╮
│  0 / 100 pts                          │
│  ░░░░░░░░░░░░░░░░░░░░  0/4 tests      │
│  2 indices utilisés, -25 pts          │
╰───────────────────────────────────────╯
ℹ Résultat enregistré dans l'historique (0/100 pts).
✘ Épreuve refusée pour deux raisons. Un contrôle bloquant a échoué, et aucune
note ne le compense :
  test_le_secret_a_servi_et_ne_survit_dans_aucune_couche
Et votre total, 0 % du barème, reste sous le seuil de 75 %.

Tentative enregistrée. Corrigez l'exigence ci-dessus, puis dsoxlab submit à
nouveau.

Regardez le verdict final : il donne deux raisons au refus, un contrôle bloquant raté, dont il nomme le test, et un total sous le seuil. Le test nommé est celui à corriger en priorité, parce qu'aucune note ne compense un contrôle bloquant : avec une note au-dessus du seuil, ce seul test suffirait à refuser l'épreuve.

Les deux autres verdicts sont plus simples. Quand tout passe, submit conclut par « Examen réussi : 100 % du barème, pour un seuil de 75 % ». Sans contrôle bloquant, une note sous le seuil donne « Examen échoué » et invite à rejouer le lab avec dsoxlab reset, puis dsoxlab run.

Que garde chaque tentative enregistrée ?

Chaque passage de check ou de submit enregistre une tentative, avec de quoi la relire après coup. Elle porte un identifiant unique, la version du lab au moment du passage, l'état de chaque critère et les indices que vous aviez vus, avec leur identifiant. Ces indices restent après un reset, qui efface pourtant les demandes d'indices du lab : l'historique dit donc toujours ce que vous aviez vu quand vous avez validé. dsoxlab scores s'appuie sur cette mémoire.

Facultatif : ce que la base locale garde, et ce qui en sort

L'export et dsoxlab push s'appuient eux aussi sur cette mémoire. Pour chaque critère, la base locale garde l'identifiant, l'état et le message écrit par l'auteur du lab, en entier. La politique du lab ne limite que ce qui sort de cette base : l'export n'en reprend que la première ligne, et rien sur une épreuve, et dsoxlab push n'envoie à votre compte que l'identifiant et l'état de chaque critère, sur un catalogue qui l'a déclaré. Le texte technique d'une exception n'est jamais conservé.

Deux cas n'inscrivent rien : un lab de type validation, qui défend un guide publié et ne note personne, et une exécution qui n'a rien mesuré, comme vu plus haut.

Comment lire l'état d'un lab avec dsoxlab status ?

dsoxlab status dit où en est le lab actif, ou celui qu'on nomme, par un état stable : not_started, ready, in_progress, validated ou degraded. Il ne parle jamais des machines : c'est le rôle de dsoxlab infra status, qui vérifie que chaque hôte répond en SSH. Sur un lab vm préparé, un panneau intitulé « État du lab », suivi du nom du lab, affiche en cours et la phrase « Préparé, le travail se fait sur la machine du lab. ». Sans lab actif, status le dit et renvoie vers run, ce que montre la réponse après un submit, qui vide le lab actif :

$ dsoxlab status
ℹ Aucun lab actif dans ce catalogue. Choisis-en un : dsoxlab run <lab>
ℹ Pour l'état de l'infrastructure, c'est désormais : dsoxlab infra status

Regardez la seconde ligne : pour l'état des machines, il faut taper dsoxlab infra status, pas status.

État	Libellé	Ce qu'il signifie
not_started	non commencé	Rien n'est préparé : dsoxlab run <lab>
ready	prêt	L'environnement est préparé, rien n'y a été touché
in_progress	en cours	Le travail a commencé : le répertoire de travail diffère de ce que run y a posé, ou la préparation d'un lab vm a eu lieu
validated	validé	Une note a été enregistrée pour ce lab
degraded	dégradé	Un service déclaré ne tourne plus, ou le moteur Docker manque ou ne répond pas

Glissez pour voir

Attention au mot « validé » : il veut dire qu'une note existe, pas que tous les tests passent. Un lab noté 0 sur 100 est « validé » au sens de status, qui affiche alors « Note obtenue : 0 / 100 ». Pour savoir si une épreuve a été réussie, regardez le verdict dans dsoxlab scores. L'état degraded prime sur les autres, parce qu'il appelle un geste immédiat : relancer le service avec dsoxlab run <lab>. dsoxlab status --json rend l'état dans un jeton stable, que l'on filtre sans dépendre de la langue.

Dépannage

Aucun de ces cas n'est une panne de l'outil : le message dit chaque fois ce qui manque ou ce qui est refusé.

Symptôme	Cause	Solution
check sort en 2 et demande de provisionner	Lab vm sans infrastructure ; rien n'est enregistré	dsoxlab provision, puis relancer check
check signale qu'aucun test n'a pu être collecté, et n'enregistre rien	pytest n'a pas pu démarrer	Lire la sortie : conftest.py qui lève, machine injoignable, dépendance absente ; dsoxlab doctor
check signale que tous les tests ont été sautés, et n'enregistre rien	Le lab n'est pas prêt : répertoire de travail non préparé ou service arrêté	dsoxlab run <id>, puis relancer check
Un critère affiche « non évalué : vérification impossible »	Le dispositif n'a pas pu vérifier ce critère	Relancer check, puis dsoxlab doctor ; ce n'est pas une faute de votre part
Aucun message d'aide sous un critère raté	Le lab est une épreuve, ou un challenge qui ne montre que la première ligne	C'est voulu : relire la mission avec dsoxlab challenge
dsoxlab -v check n'affiche pas la sortie complète	Le lab est une épreuve	Aucun détail n'est disponible sur une épreuve
dsoxlab check <lab> -v répond « No such option: -v »	-v est une option globale, elle se place avant la commande	dsoxlab -v check <lab>
submit refuse une épreuve à 80 % pour un seuil de 75 %	Un contrôle bloquant a échoué	Corriger le test nommé, puis dsoxlab submit
status affiche « validé » avec 0 / 100	« validé » signifie qu'une note existe	Relire le résumé de check, corriger, relancer

Glissez pour voir

À retenir

• check enregistre une tentative à chaque passage, ratée comprise ; submit fait de même puis clôt la session.
• Un critère est satisfait, non satisfait, non évalué ou sauté ; non évalué n'est pas votre faute, et un test sauté n'apparaît pas dans « Ce qui reste à faire ».
• Le retour dépend du type de lab : message complet sur un lab guidé, libellé et première ligne sur un challenge, verdict seul sur une épreuve.
• Sur une épreuve, même dsoxlab -v check et check --json ne donnent aucun détail (output_withheld), et un contrôle bloquant raté la refuse quel que soit le total.
• Rien n'est enregistré si aucun test n'a pu être mesuré, ni pour un lab validation.
• -v se place avant la commande : dsoxlab -v check <lab>.
• status dit où en est le lab ; « validé » signifie qu'une note existe.

Contrôle de connaissances

Vérifiez que l'essentiel de ce guide est acquis. Les questions portent uniquement sur ce qui vient d'être expliqué ici.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

8 questions

6 min.

70% requis

Informations

• Le chronomètre démarre au clic sur Démarrer
• Questions à choix multiples, vrai/faux et réponses courtes
• Vous pouvez naviguer entre les questions
• Les résultats détaillés sont affichés à la fin

Démarrer le quiz

Lance le quiz et démarre le chronomètre

×

📖 Voir la documentation →