Creating Exercises: Writing the Assignment and Test Suite

If you used the template repository in the previous step of the guide, your repository already contains an exercise (EchoFunction). Now, we will add another exercise ourselves. The existing exercise can, of course, serve as an example.

Creating Files and Folders

1. Select the folder where you want to create the file or folder.
2. Use the icons at the top to create a file or folder. You can also right-click on the folder and choose New File... or New Folder....
3. Type the name of the file (including the extension) or folder. Preferably, choose a name without spaces.
4. Confirm with Enter.

The result of this guide (the complete exercise) can also be found in our example repository.

1. Structure

Each exercise in Dodona corresponds to a specific folder in the exercise repository. This folder follows a fixed structure, which we will now create.

First, create a new folder for the exercise, which we will name minimum. Then, inside this new folder, create three additional folders:

• description: folder containing the assignment
• evaluation: folder with information on how a solution should be assessed
• solution: folder containing a sample solution

The folder structure for this exercise should look like this:

exercises/
└── minimum/
   ├── evaluation/
   ├── description/
   └── solution/

2. Configuration

Dodona requires a configuration file for each exercise. This file contains metadata used by Dodona.

Create the file config.json inside the minimum folder with the following content:

{
  "description": {
    "names": {
      "en": "Minimum",
      "nl": "Minimum"
    }
  },
  "evaluation": {
    "handler": "tested",
    "test_suite": "suite.yaml"
  },
  "programming_language": "python",
  "access": "private"
}

This file specifies several things:

• description.names: The names of the exercise as shown in Dodona in Dutch (nl) and English (en). In this case, the names are identical.
• evaluation.handler: We use TESTed as the judge.
• evaluation.test_suite: The test suite is named suite.yaml.
• programming_language: The programming language of the exercise. Here, we choose Python.
• access: The access level is private. We choose a private exercise because this is just a guide, but we encourage making your exercises public (public) so that other teachers can use them (just as you have access to thousands of public exercises on Dodona).

After creating this file, your repository structure should look like this:

exercises/
└── minimum/
   ├── evaluation/
   ├── description/
   ├── solution/
   └── config.json

3. Assignment and Sample Solution

The next step is to define the assignment. This is what students will see when they attempt the exercise, guiding them on what they need to do.

Create a file description.en.md inside the description folder of the exercise, with the following content:

Write a function `minimum` that accepts two numbers as arguments.
This function should return the smaller of the two.

### Example

```console?lang=python&prompt=>>>
>>> minimum(5, 6)
5
```

If you also want to provide a Dutch version of the assignment, create another file named description.nl.md. The assignment is written in Markdown, a fairly simple formatting language. More information about Markdown can be found here.

We will also add a sample solution. This is not required, but it is often useful to have. Students cannot see this solution (unless your repository is public, of course).

Create a file solution.py inside the solution folder with the following content:

def minimum(a, b):
    if a < b:
        return a
    else:
        return b

After creating these two files, your repository should now look like this:

exercises/
└── minimum/
   ├── evaluation/
   ├── description/
   |  └── description.nl.md
   ├── solution/
   |  └── solution.py
   └── config.json

4. Creating a Test Suite

We want this exercise to be automatically graded. To achieve this, we need to write a test suite that tells Dodona which tests should be run. If all test cases pass, Dodona considers the student's submitted solution to be correct.

In this case, we will keep the test plan brief, with only a few test cases. In a real exercise, you would likely want to include more test cases.

Create a file suite.yaml inside the evaluation folder of the exercise, with the following content:

- 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 this test suite, several things happen:

• The test cases are grouped under a tab named "minimum".
• There are 5 test cases.
• Each test case defines an expression: the function call that should be executed. We use Python syntax for this. In this case, we call the function that students need to implement with different arguments.
• We also define the expected return value for each test case.

Finally, the complete file structure should look like this:

exercises/
└── minimum/
   ├── evaluation/
   |  └── suite.yaml
   ├── description/
   |  └── description.en.md
   ├── solution/
   |  └── solution.py
   └── config.json

5. Saving Changes

Now that the exercise is ready, we need to save the changes to the repository (that means committing the changes in the repo). Do this as follows:

1. Click on the Source Control icon on the left.
2. At the top of the list of changes, click the + button to stage all files (Stage All Changes).
3. Enter a commit message at the top. Describe what you have done, such as "Add my first exercise".
4. Click the Commit & Push button. If you get a pop-up, choose Sync (Push & Pull).

If everything went well, this window should now be empty.

6. Testing the Exercise

The exercise you just created can be found in your exercise repository on Dodona. Your new exercise is now available as a concept on Dodona.

Before you can publish an exercise (removing it from concept status), Dodona checks whether three conditions are met:

• The exercise must have a valid configuration file.
• The exercise must have a name and description.
• You must submit at least one correct solution.

If you followed this guide, the first two conditions are already met. You only need to submit a correct solution, which we have already created. To do this, click on the info icon in the top menu bar:

Next, select the sample solution you want to submit (in this case, there is only one: solution.py), then click the Submit this solution button. This will open the exercise page with the sample solution preloaded. All you need to do is click submit.

Once the solution is marked as correct, you will be able to publish the exercise by clicking Publish this exercise. Your exercise is now ready to use on Dodona!

TIP

Let someone else try your exercise. This often helps you discover gaps in the test suite and refine the exercise further.