Oefeningen opstellen: opgave en testplan schrijven
Als je in de vorige stap van de handleiding de template repository gebruikt hebt, bevat je repository al een oefening (de Echofunctie). Hier zullen we nu zelf nog een oefening toevoegen. De bestaande oefening kan uiteraard als voorbeeld dienen.
Bestanden en mappen maken
- Selecteer de map waarin je het bestand of de map wil aanmaken.
- Gebruik de icoontjes bovenaan om een bestand of map aan te maken. Rechtsklikken op de map en kiezen voor
New File...
ofNew Folder...
kan ook. - Typ de naam van het bestand (inclusief extensie) of map. Kies bij voorkeur een naam zonder spaties.
- Bevestig met Enter.
Het resultaat van deze handleiding (de volledige oefening) kan je ook vinden in onze repository met voorbeelden.
1. Structuur
Elke oefening in Dodona komt overeen met een bepaalde map in de oefeningenrepository. Die map heeft een vaste structuur, die we nu zullen maken.
Maak dus eerst een nieuwe map voor de oefening, die we minimum
zullen noemen. Maak daarna, in deze nieuwe map, nog drie mappen:
description
: map waarin de opgave komtevaluation
: map met informatie over hoe een oplossing beoordeeld moet wordensolution
: map waarin een voorbeeldoplossing komt
De map voor deze oefening moet er als volgt uitzien:
exercises/
└── minimum/
├── evaluation/
├── description/
└── solution/
2. Configuratie
Dodona eist voor elke oefeningen ook een configuratiebestand. Dit bestand bevat metadata, die door Dodona gebruikt worden.
Maak het bestand config.json
in de map minimum
met de volgende inhoud:
{
"description": {
"names": {
"en": "Minimum",
"nl": "Minimum"
}
},
"evaluation": {
"handler": "tested",
"test_suite": "suite.yaml"
},
"programming_language": "python",
"access": "private"
}
In dit bestand worden een aantal dingen gespecifieerd:
description.names
: De namen van de oefening zoals getoond door Dodona in het Nederlands (nl) en in het Engels (en). In dit geval zijn de namen gelijk.evaluation.handler
: We gebruiken TESTed als judge.evaluation.test_suite
: Het testplan krijgt de naamsuite.yaml
.programming_language
: De programmeertaal van de oefening: hier kies je in welke programmeertaal je de oplossingen wilt. In dit geval is dat Python.access
: Het toegangsniveau is hier private. We kiezen voor een private oefening omdat dit maar een handleiding is, maar we moedigen aan om je oefeningen publiek (public) te zetten: dan kunnen andere leerkrachten er ook gebruik van maken (net zoals jij de keuze hebt uit duizenden publieke oefeningen op Dodona).
Nadat je dit bestand gemaakt hebt, zal je repository er zo uitzien:
exercises/
└── minimum/
├── evaluation/
├── description/
├── solution/
└── config.json
3. Opgave en voorbeeldoplossing
De volgende stap is de opgave van de oefening. Dit krijgen leerlingen en studenten te zien wanneer ze de oefening willen oplossen en vertelt hen wat ze moeten doen.
Maak een bestand description.nl.md
aan in de map description
van de oefening, met volgende inhoud:
Schrijf een functie `minimum` die twee getallen als argumenten aanvaardt.
Deze functie moet het kleinste geval van die twee teruggeven.
### Voorbeeld
```console?lang=python&prompt=>>>
>>> minimum(5, 6)
5
```
Als je ook een Engelstalige opgave wilt maken, gebruik je de naam description.en.md
voor het tweede bestand. De opgave zelf wordt geschreven in Markdown, een redelijk eenvoudig opmaakformaat. Meer informatie over Markdown is hier te vinden.
We voegen ook direct een voorbeeldoplossing toe. Dit is niet verplicht, maar vaak is het wel handig om te hebben. Leerlingen kunnen deze voorbeeldoplossing niet zien (tenzij je repository publiek staat natuurlijk).
Maak een bestand solution.py
aan in de map solution
met volgende inhoud:
def minimum(a, b):
if a < b:
return a
else:
return b
Nadat je deze twee bestanden gemaakt hebt, moet je repository er zo uitzien:
exercises/
└── minimum/
├── evaluation/
├── description/
| └── description.nl.md
├── solution/
| └── solution.py
└── config.json
4. Een testplan maken
We willen dat deze oefening automatisch getest wordt. Hiervoor moeten we een testplan schrijven, waarin we Dodona vertellen welke testen we allemaal willen uitvoeren. Als alle testgevallen geslaagd zijn, is de ingediende oplossing van de student volgens Dodona correct.
In dit geval houden we het testplan kort, met slechts een beperkt aantal testgevallen. In een echte oefening wil je waarschijnlijk meer testgevallen voorzien.
Maak een bestand suite.yaml
aan in de map evaluation
van de oefening, met volgende inhoud:
- tab: "minimum"
testcases:
- expression: "minimum(5, 6)"
return: 5
- expression: "minimum(1.2, 1.96)"
return: 1.2
- expression: "minimum(1000000000, -5)"
return: -5
- expression: "minimum(-5, -6)"
return: -6
- expression: "minimum(6, 6)"
return: 6
In dit testplan gebeuren een aantal dingen:
- De tabbladen vanop Dodona komen overeen met het testplan. Alle testgevallen zitten hier in één tabblad, met als naam "minimum".
- Er zijn 5 testgevallen.
- Voor elk testgeval definiëren we een expressie: wat er uitgevoerd moet worden. Hiervoor gebruik je de Python-syntax. In dit geval voeren we de functie die de leerlingen moeten maken uit met verschillende parameters.
- We definiëren ook de verwachte returnwaarde voor elk testgeval.
Finaal ziet de bestandsstructuur er dus als volgt uit:
exercises/
└── minimum/
├── evaluation/
| └── suite.yaml
├── description/
| └── description.nl.md
├── solution/
| └── solution.py
└── config.json
5. Wijzigingen opslaan
Nu de oefening klaar is, moeten we de wijzigingen opslaan in de repository (dat wil zeggen de wijzigingen committen in de repo). Doe dit als volgt:
- Klik aan de linkerkant op het icoontje voor Source Control.
- Klik bovenaan de lijst met wijzigingen op de knop met
+
om alle bestanden klaar te zetten (Stage All Changes). - Kies bovenaan een commit message. Hierin beschrijf je wat je gedaan hebt, zoals "Voeg mijn eerste oefening toe".
- Klik op de knop
Commit & Push
. Als je een pop-up krijgt, kies je voorSync (Push & Pull)
.
Als alles goed gegaan is, werd dit venster leeg.
6. Oefening testen
De oefening die je daarnet gemaakt hebt, kan je terugvinden in jouw oefeningenrepository op Dodona. Je nieuwe oefening is nu beschikbaar als concept op Dodona.
Vooraleer je een oefening kan publiceren (uit concept halen), controleert Dodona of aan drie voorwaarden voldaan is:
- De oefening moet een geldig configuratiebestand hebben.
- De oefening moet een naam en een beschrijving hebben.
- Je moet minstens één correcte oplossing indienen.
Als je deze handleiding gevolgd hebt, zijn aan de eerste twee voorwaarden al voldaan. Je moet enkel nog een juiste oplossing indienen, die we al gemaakt hebben. Om dit te doen klik je bovenaan de menubalk op het informatie-icoontje:
Vervolgens kies je de voorbeeldoplossing die je wilt indienen (hier is er maar een: `solution.py), waarna je op de knop Deze oplossing indienen klikt. Dit zal de oefeningenpagina openen met de voorbeeldoplossing ingeladen. Je moet enkel nog op indienen klikken.
Eens de oplossing juist gerekend is, zal je de oefening kunnen publiceren door op Deze oefening publiceren te klikken. Je oefening is nu klaar om te gebruiken op Dodona!
TIP
Laat je oefening eens oplossen door iemand anders. Zo ontdek je vaak nog gaten in het testplan, en kan je de oefening verder verfijnen.