diff --git a/README.md b/README.md
index ccefac4e7dd98836bc55400a1f10272caa5d290c..5d5181d4b69d657af0c1bcf674b9bf26eb5de2ff 100644
--- a/README.md
+++ b/README.md
@@ -10,22 +10,25 @@ and an easy and safe mechanism for verifying results.
- Hint-system collects hints from code and display it with failed unittests
- A dashboard gives the students an overview of their progress
- Safe and convenient to administer
-
+ -
### Why this instead of an online autograder?
-Online autograding services will often say that they have adapter their particular model in order to make students better or happier. I did a small thought-experiments, and asked myself what I would ideally want out of an autograder if I was a student. I quickly realized the only thing I really cared about was easily it allowed me to fix bugs in my homework assignments. In other words, I think students prioritize the same thing as we all do when we write software tests -- to quickly and easily fix problems.
+Online autograding services often say that they have adapter their particular model in order to make students better or happier. I did a small thought-experiments, and asked myself what I would ideally want out of an autograder if I was a student. I quickly realized the only thing I really cared about was easily it allowed me to fix bugs in my homework assignments. In other words, I think students prioritize the same thing as we all do when we write software tests -- to quickly and easily identify and fix problems.
-However, I don't think an online autograder is a test-system I would like to use for any of my software projects.
+However, I would not use an online autograder for any of my own software projects for a number of reasons:
- Why would I want my tests to be executed in another environment than my development-environment?
- Why would I want to copy-paste code online (or rely on a sub-standard web-IDE without autocomplete?)
- The lack of a debugger would drive me nuts
- - Why even have an external tool when my IDE has excellent test plugins?
+ - Why `alt+tab` to an external tool when my IDE already has excellent test plugins?
+ - *Your test will be run within a few minutes*
+ - Something as basic as `print`-statements is often not readily available; I don't know any services that shows them live
+ - Often students have no access to the tests themselves, perhaps because they rely on special terminal commands. This means it can be hard to reason about what code is *actually* being run.
-Simply put, I'd never want to use an online autograder as a way to fix issues in my own software projects, so why should students prefer it?
+This raises the question that if I would not want to use an online autograder as a way to fix issues in my own software projects, why should students prefer it?
-The alternative is obvious -- simply give students a suite of unittests. This raises some potential issues such as safety and administrative convenience, but they turned out to be easy to solve.
+The alternative is in my view obvious -- simply give students a suite of unittests. This raises some potential issues such as safety and administrative convenience, but they turned out to be easy to solve. If you want to learn more about developing tests see the test-development repository here: https://gitlab.compute.dtu.dk/tuhe/unitgrade_private
## Installation
-Unitgrade requires python 3.8 or higher, can be installed using `pip`:
+Unitgrade requires python 3.8 or higher, and can be installed using `pip`:
```terminal
pip install unitgrade
```
@@ -45,19 +48,18 @@ When you are done, you should be able to import unitgrade. Type `python` in the
```
## Using Unitgrade
-In unitgrade, your homework assignments are called **reports** and are distributed as regular `.py`-files. I am going to use `cs101report1.py` as a generic example in the following, but a real-world example can be found here: https://gitlab.compute.dtu.dk/tuhe/unitgrade_private/-/blob/master/examples/example_simplest/students/cs101/report1.py .
+Your homework assignments are called **reports** and are distributed as a regular `.py`-files. In the following I will use `cs101report1.py` as an example, and you can find a real-world example here: https://gitlab.compute.dtu.dk/tuhe/unitgrade_private/-/blob/master/examples/example_simplest/students/cs101/report1.py .
-The report is simply a collection of questions which are individually scored, and each question may in turn involve checking several sub-cases.
+A report is simply a collection of questions, and each question may in turn involve several tests.
-You should think of the tests as a help for you when you are debugging your code and when you are trying to figure out what to do.
-I recommend running the tests through your IDE. In pycharm, this is as simple as right-clicking on the test and selecting `Run as unittest`. The image belows shows the outcome in Pycharm:
+I recommend running the tests through your IDE. In pycharm, this is as simple as right-clicking on the test and selecting `Run as unittest`:
-The tests are shown in the lower-left corner, and in this case they are all green meaning they have passed. If a test fails, you can right-click and select `debug as unittest`, or you can click on it and see the output it produced, and you can right-click on individual tests to re-run them.
+The outcome of the tests are shown in the lower-left corner, and in this case they are all green meaning they have passed. You can see the console output generated by a test by clicking on it. If a test fails, you can select `debug as unittest` from the menu above to launch a debugger, and you can right-click on individual tests to re-run them.
### Checking your score
-To check your score, you have to run the main script (`cs101report1.py`) as a regular python file. This can be done either through pycharm (Hint: Open the file and press `alt-shift-F10`) or in the console by running the command:
+To check your score, you have to run the main script (`cs101report1.py`). This can be done either through pycharm (Hint: Open the file and press `alt-shift-F10`) or in the console by running the command:
```
python cs101report1.py
```
@@ -68,7 +70,7 @@ The file will run and show an output where the score of each question is compute
| | | |_ __ _| |_| | \/_ __ __ _ __| | ___
| | | | '_ \| | __| | __| '__/ _` |/ _` |/ _ \
| |_| | | | | | |_| |_\ \ | | (_| | (_| | __/
- \___/|_| |_|_|\__|\____/_| \__,_|\__,_|\___| v0.1.29.0, started: 16/09/2022 12:49:50
+ \___/|_| |_|_|\__|\____/_| \__,_|\__,_|\___| v0.1.29.0, started: 16/09/2022 13:40:21
02531 week 5: Looping (use --help for options)
Question 1: Cluster analysis
@@ -101,7 +103,7 @@ Question 4: Fermentation rate
* q4.4) fermentationRate([20.1, 19.3, 1.1, 18.2, 19.7, ...], 18.2, 20) = 19.500 ?..................................PASS
* q4) Total.................................................................................................... 10/10
-Total points at 12:49:54 (0 minutes, 4 seconds)....................................................................40/40
+Total points at 13:40:26 (0 minutes, 4 seconds)....................................................................40/40
Provisional evaluation
--------- -----
q1) Total 10/10
@@ -129,27 +131,32 @@ I recommend to watch and run the tests from your IDE, as this allows you to use
```
unitgrade
```
-in a terminal from a directory that contains a test (the directory will be searched recursively for tests). This will start a small background service and open this page:
+from a directory that contains a test (the directory will be searched recursively for tests). The command will start a small background service and open this page:
-What currently works:
+Features supported in the current version:
- Shows you which files need to be edited to solve the problem
- - Collect hints given in the homework files
- - fully responsive -- the terminal will update while the test is running regardless of where you launch the test
+ - Collect hints given in the homework files and display them for the relevant tests
+ - fully responsive -- the UI, including the terminal, will update while the test is running regardless of where you launch the test
- Allows you to re-run tests
- Shows current test status and results captured in `.token`-file
- Tested on Windows/Linux
+ - No binaries or special setup required; everything is 100% python
Note that the run feature currently assumes that your system-wide `python` command can run the tests. This may not be the case if you are using virtual environments -- I expect to fix this soon.
### Why are there two scripts?
-The reason why we use a standard test script (one with the `_grade.py` extension and one without), is because the tests should both be easy to debug, but at the same time we have to avoid accidential changes to the test scripts. The tests themselves are the same, so if one script works, so should the other.
+
# FAQ
+
+ - **Why is there two scripts?**
+The reason why we use a standard test script (one with the `_grade.py` extension and one without), is because the tests should both be easy to debug, but at the same time we have to avoid accidential changes to the test scripts. The tests themselves are the same, so if one script works, so should the other.
+
- **My non-grade script and the `_grade.py` script gives different number of points**
-Since the two scripts should contain the same code, the reason is nearly certainly that you have made an (accidental) change to the test scripts. Please ensure both scripts are up-to-date and if the problem persists, try to get support.
+Since the two scripts should contain the same code, the reason is with near certainty that you have made an (accidental) change to the test scripts. Please ensure both scripts are up-to-date and if the problem persists, get support.
- - **Why is there a `unitgrade` directory with a bunch of pickle files? Should I also upload them?**
+ - **Why is there a `unitgrade`-directory with a bunch of pickle files? Should I also upload them?**
No. The file contains the pre-computed test results your code is compared against. You should only upload the `.token` file, nothing else
- **I am worried you might think I cheated because I opened the '_grade.py' script/token file**
@@ -159,14 +166,14 @@ This should not be a concern. Both files are in a binary format (i.e., if you op
Feel free to edit/break this file as much as you like if it helps you work out the correct solution. However, since the `report1_grade.py` script contains a seperate version of the tests, please ensure both files are in sync to avoid unexpected behavior.
### Debugging your code/making the tests pass
-The course material should contain information about the intended function of the scripts used in the tests, and the file `report1.py` should mainly be used to check which of your code is being run. In other words, first make sure your code solves the exercises, and only later run the test script which is less easy/nice to read.
-However, obivously you might get to a situation where your code seems to work, but a test fails. In that case, it is worth looking into the code in `report1.py` to work out what is going on.
+The course material should contain information about the intended function of the scripts, and the file `report1.py` should mainly be used to check which of your code is being run. In other words, first make sure your code solves the exercises, and only later run the test script which is less easy/nice to read.
+However, obivously you might get to a situation where your code seems to work, but a test fails. In that case, it is worth looking into the code in `report1.py` to work out what exactly is going on.
- **I am 99% sure my code is correct, but the test still fails. Why is that?**
The testing framework offers a great deal of flexibility in terms of what is compared. This is either: (i) The value a function returns, (ii) what the code print to the console (iii) something derived from these.
When a test fails, you should always try to insert a breakpoint on exactly the line that generate the problem, run the test in the debugger, and figure out what the expected result was supposed to be. This should give you a clear hint as to what may be wrong.
-One possibility that might trick some is that if the test compares a value computed by your code, the datatype of that value is important. For instance, a `list` is not the same as a python `ndarray`, and a `tuple` is different from a `list`. This is the correct behavior of a test: These things are not alike and correct code should not confuse them.
+One possibility that might trick some is that if the test compares a value computed by your code, the datatype of that value may be important. For instance, a `list` is not the same as a python `ndarray`, and a `tuple` is different from a `list`.
- **The `report1.py` class is really confusing. I can see the code it runs on my computer, but not the expected output. Why is it like this?**
To make sure the desired output of the tests is always up to date, the tests are computed from a working version of the code and loaded from the disk rather than being hard-coded.
@@ -178,16 +185,16 @@ Note these are disabled for the `report1_grade.py` script to avoid confusion. It
- **Since I cannot read the `.token` file, can I trust it contains the same number of points internally as the file name indicate?**
Yes.
-
+
### Privacy/security
- **I managed to reverse engineer the `report1_grade.py`/`*.token` files in about 30 minutes. If the safety measures are so easily broken, how do you ensure people do not cheat?**
-That the script `report1_grade.py` is difficult to read is not the principle safety measure. Instead, it ensures there is no accidential tampering. If you muck around with these files and upload the result, we will very likely know.
+That the script `report1_grade.py` is difficult to read is not the principle safety measure. Instead, it ensures there is no accidential tampering. If you muck around with these files and upload the result, we will very likely know you edited them.
- **I have private data on my computer. Will this be read or uploaded?**
-No. The code will look for and upload your solutions, but it will not read/look at other directories in your computer. As long as your keep your private files out of the directory containing your homework you have nothing to worry about.
+No. The code will look for and include yours solutions in the `.token`-file, but it will not read/look at other directories in your computer. As long as your keep your private files out of the directory that contains your homework you have nothing to worry about.
- **Does this code install any spyware/etc.? Does it communicate with a website/online service?**
-No. Unitgrade makes no changes outside the courseware directory and it does not do anything tricky. It reads/runs code and produce the `.token` file.
+Unitgrade makes no changes outside the courseware directory, and it does not do anything tricky. It reads/runs code and produces the `.token` file. The development version of unitgrade has an experimental feature to look at a github page and check your version fo the tests is up-to-date, but this is currently not enabled and all this would do is to warn you about a potential problem with an outdated test.
- **I still have concerns about running code on my computer I cannot easily read**
Please contact me and we can discuss your specific concerns.
diff --git a/docs/README.jinja.md b/docs/README.jinja.md
index 86313314df439a3b7148299d299963a9add07f0e..5901661ad09e77b1e63e55fb52227186ed351e26 100644
--- a/docs/README.jinja.md
+++ b/docs/README.jinja.md
@@ -10,22 +10,25 @@ and an easy and safe mechanism for verifying results.
- Hint-system collects hints from code and display it with failed unittests
- A dashboard gives the students an overview of their progress
- Safe and convenient to administer
-
+ -
### Why this instead of an online autograder?
-Online autograding services will often say that they have adapter their particular model in order to make students better or happier. I did a small thought-experiments, and asked myself what I would ideally want out of an autograder if I was a student. I quickly realized the only thing I really cared about was easily it allowed me to fix bugs in my homework assignments. In other words, I think students prioritize the same thing as we all do when we write software tests -- to quickly and easily fix problems.
+Online autograding services often say that they have adapter their particular model in order to make students better or happier. I did a small thought-experiments, and asked myself what I would ideally want out of an autograder if I was a student. I quickly realized the only thing I really cared about was easily it allowed me to fix bugs in my homework assignments. In other words, I think students prioritize the same thing as we all do when we write software tests -- to quickly and easily identify and fix problems.
-However, I don't think an online autograder is a test-system I would like to use for any of my software projects.
+However, I would not use an online autograder for any of my own software projects for a number of reasons:
- Why would I want my tests to be executed in another environment than my development-environment?
- Why would I want to copy-paste code online (or rely on a sub-standard web-IDE without autocomplete?)
- The lack of a debugger would drive me nuts
- - Why even have an external tool when my IDE has excellent test plugins?
+ - Why `alt+tab` to an external tool when my IDE already has excellent test plugins?
+ - *Your test will be run within a few minutes*
+ - Something as basic as `print`-statements is often not readily available; I don't know any services that shows them live
+ - Often students have no access to the tests themselves, perhaps because they rely on special terminal commands. This means it can be hard to reason about what code is *actually* being run.
-Simply put, I'd never want to use an online autograder as a way to fix issues in my own software projects, so why should students prefer it?
+This raises the question that if I would not want to use an online autograder as a way to fix issues in my own software projects, why should students prefer it?
-The alternative is obvious -- simply give students a suite of unittests. This raises some potential issues such as safety and administrative convenience, but they turned out to be easy to solve.
+The alternative is in my view obvious -- simply give students a suite of unittests. This raises some potential issues such as safety and administrative convenience, but they turned out to be easy to solve. If you want to learn more about developing tests see the test-development repository here: https://gitlab.compute.dtu.dk/tuhe/unitgrade_private
## Installation
-Unitgrade requires python 3.8 or higher, can be installed using `pip`:
+Unitgrade requires python 3.8 or higher, and can be installed using `pip`:
```terminal
pip install unitgrade
```
@@ -45,19 +48,18 @@ When you are done, you should be able to import unitgrade. Type `python` in the
```
## Using Unitgrade
-In unitgrade, your homework assignments are called **reports** and are distributed as regular `.py`-files. I am going to use `cs101report1.py` as a generic example in the following, but a real-world example can be found here: https://gitlab.compute.dtu.dk/tuhe/unitgrade_private/-/blob/master/examples/example_simplest/students/cs101/report1.py .
+Your homework assignments are called **reports** and are distributed as a regular `.py`-files. In the following I will use `cs101report1.py` as an example, and you can find a real-world example here: https://gitlab.compute.dtu.dk/tuhe/unitgrade_private/-/blob/master/examples/example_simplest/students/cs101/report1.py .
-The report is simply a collection of questions which are individually scored, and each question may in turn involve checking several sub-cases.
+A report is simply a collection of questions, and each question may in turn involve several tests.
-You should think of the tests as a help for you when you are debugging your code and when you are trying to figure out what to do.
-I recommend running the tests through your IDE. In pycharm, this is as simple as right-clicking on the test and selecting `Run as unittest`. The image belows shows the outcome in Pycharm:
+I recommend running the tests through your IDE. In pycharm, this is as simple as right-clicking on the test and selecting `Run as unittest`:
-The tests are shown in the lower-left corner, and in this case they are all green meaning they have passed. If a test fails, you can right-click and select `debug as unittest`, or you can click on it and see the output it produced, and you can right-click on individual tests to re-run them.
+The outcome of the tests are shown in the lower-left corner, and in this case they are all green meaning they have passed. You can see the console output generated by a test by clicking on it. If a test fails, you can select `debug as unittest` from the menu above to launch a debugger, and you can right-click on individual tests to re-run them.
### Checking your score
-To check your score, you have to run the main script (`cs101report1.py`) as a regular python file. This can be done either through pycharm (Hint: Open the file and press `alt-shift-F10`) or in the console by running the command:
+To check your score, you have to run the main script (`cs101report1.py`). This can be done either through pycharm (Hint: Open the file and press `alt-shift-F10`) or in the console by running the command:
```
python cs101report1.py
```
@@ -77,27 +79,32 @@ I recommend to watch and run the tests from your IDE, as this allows you to use
```
unitgrade
```
-in a terminal from a directory that contains a test (the directory will be searched recursively for tests). This will start a small background service and open this page:
+from a directory that contains a test (the directory will be searched recursively for tests). The command will start a small background service and open this page:
-What currently works:
+Features supported in the current version:
- Shows you which files need to be edited to solve the problem
- - Collect hints given in the homework files
- - fully responsive -- the terminal will update while the test is running regardless of where you launch the test
+ - Collect hints given in the homework files and display them for the relevant tests
+ - fully responsive -- the UI, including the terminal, will update while the test is running regardless of where you launch the test
- Allows you to re-run tests
- Shows current test status and results captured in `.token`-file
- Tested on Windows/Linux
+ - No binaries or special setup required; everything is 100% python
Note that the run feature currently assumes that your system-wide `python` command can run the tests. This may not be the case if you are using virtual environments -- I expect to fix this soon.
### Why are there two scripts?
-The reason why we use a standard test script (one with the `_grade.py` extension and one without), is because the tests should both be easy to debug, but at the same time we have to avoid accidential changes to the test scripts. The tests themselves are the same, so if one script works, so should the other.
+
# FAQ
+
+ - **Why is there two scripts?**
+The reason why we use a standard test script (one with the `_grade.py` extension and one without), is because the tests should both be easy to debug, but at the same time we have to avoid accidential changes to the test scripts. The tests themselves are the same, so if one script works, so should the other.
+
- **My non-grade script and the `_grade.py` script gives different number of points**
-Since the two scripts should contain the same code, the reason is nearly certainly that you have made an (accidental) change to the test scripts. Please ensure both scripts are up-to-date and if the problem persists, try to get support.
+Since the two scripts should contain the same code, the reason is with near certainty that you have made an (accidental) change to the test scripts. Please ensure both scripts are up-to-date and if the problem persists, get support.
- - **Why is there a `unitgrade` directory with a bunch of pickle files? Should I also upload them?**
+ - **Why is there a `unitgrade`-directory with a bunch of pickle files? Should I also upload them?**
No. The file contains the pre-computed test results your code is compared against. You should only upload the `.token` file, nothing else
- **I am worried you might think I cheated because I opened the '_grade.py' script/token file**
@@ -107,14 +114,14 @@ This should not be a concern. Both files are in a binary format (i.e., if you op
Feel free to edit/break this file as much as you like if it helps you work out the correct solution. However, since the `report1_grade.py` script contains a seperate version of the tests, please ensure both files are in sync to avoid unexpected behavior.
### Debugging your code/making the tests pass
-The course material should contain information about the intended function of the scripts used in the tests, and the file `report1.py` should mainly be used to check which of your code is being run. In other words, first make sure your code solves the exercises, and only later run the test script which is less easy/nice to read.
-However, obivously you might get to a situation where your code seems to work, but a test fails. In that case, it is worth looking into the code in `report1.py` to work out what is going on.
+The course material should contain information about the intended function of the scripts, and the file `report1.py` should mainly be used to check which of your code is being run. In other words, first make sure your code solves the exercises, and only later run the test script which is less easy/nice to read.
+However, obivously you might get to a situation where your code seems to work, but a test fails. In that case, it is worth looking into the code in `report1.py` to work out what exactly is going on.
- **I am 99% sure my code is correct, but the test still fails. Why is that?**
The testing framework offers a great deal of flexibility in terms of what is compared. This is either: (i) The value a function returns, (ii) what the code print to the console (iii) something derived from these.
When a test fails, you should always try to insert a breakpoint on exactly the line that generate the problem, run the test in the debugger, and figure out what the expected result was supposed to be. This should give you a clear hint as to what may be wrong.
-One possibility that might trick some is that if the test compares a value computed by your code, the datatype of that value is important. For instance, a `list` is not the same as a python `ndarray`, and a `tuple` is different from a `list`. This is the correct behavior of a test: These things are not alike and correct code should not confuse them.
+One possibility that might trick some is that if the test compares a value computed by your code, the datatype of that value may be important. For instance, a `list` is not the same as a python `ndarray`, and a `tuple` is different from a `list`.
- **The `report1.py` class is really confusing. I can see the code it runs on my computer, but not the expected output. Why is it like this?**
To make sure the desired output of the tests is always up to date, the tests are computed from a working version of the code and loaded from the disk rather than being hard-coded.
@@ -126,16 +133,16 @@ Note these are disabled for the `report1_grade.py` script to avoid confusion. It
- **Since I cannot read the `.token` file, can I trust it contains the same number of points internally as the file name indicate?**
Yes.
-
+
### Privacy/security
- **I managed to reverse engineer the `report1_grade.py`/`*.token` files in about 30 minutes. If the safety measures are so easily broken, how do you ensure people do not cheat?**
-That the script `report1_grade.py` is difficult to read is not the principle safety measure. Instead, it ensures there is no accidential tampering. If you muck around with these files and upload the result, we will very likely know.
+That the script `report1_grade.py` is difficult to read is not the principle safety measure. Instead, it ensures there is no accidential tampering. If you muck around with these files and upload the result, we will very likely know you edited them.
- **I have private data on my computer. Will this be read or uploaded?**
-No. The code will look for and upload your solutions, but it will not read/look at other directories in your computer. As long as your keep your private files out of the directory containing your homework you have nothing to worry about.
+No. The code will look for and include yours solutions in the `.token`-file, but it will not read/look at other directories in your computer. As long as your keep your private files out of the directory that contains your homework you have nothing to worry about.
- **Does this code install any spyware/etc.? Does it communicate with a website/online service?**
-No. Unitgrade makes no changes outside the courseware directory and it does not do anything tricky. It reads/runs code and produce the `.token` file.
+Unitgrade makes no changes outside the courseware directory, and it does not do anything tricky. It reads/runs code and produces the `.token` file. The development version of unitgrade has an experimental feature to look at a github page and check your version fo the tests is up-to-date, but this is currently not enabled and all this would do is to warn you about a potential problem with an outdated test.
- **I still have concerns about running code on my computer I cannot easily read**
Please contact me and we can discuss your specific concerns.
diff --git a/docs/dashboard.png b/docs/dashboard.png
index 924f91becfc648ec4b4415e40b834d24a3b30336..d7560fbbd6cf14b3b65f11568183a86dac598ccb 100644
Binary files a/docs/dashboard.png and b/docs/dashboard.png differ