Welcome to Zesje

Zesje is an online grading system for written exams.

Running Zesje

Running Zesje using Docker

Running Zesje using Docker is the easiest method to run Zesje yourself with minimal technical knowledge required. For this approach we assume that you already have Docker installed, cloned the Zesje repository and entered its directory.

First create a volume to store the data:

docker volume create zesje

Then build the Docker image using the following below. Anytime you update Zesje by pulling the repository you have to run this command again.

docker build -f auto.Dockerfile . -t zesje:auto

Finally, you can run the container to start Zesje using:

docker run -p 8881:80 --volume zesje:/app/data-dev -it zesje:auto

Zesje should be available at http://127.0.0.1:8881. If you get the error 502 - Bad Gateway it means that Zesje is still starting.

Development

Setting up a development environment

Zesje currently doesn't support native Windows, but WSL works.

We recommend using the Conda tool for managing your development environment. If you already have Anaconda or Miniconda installed, you may skip this step.

Install Miniconda by following the instructions on this page:

https://conda.io/miniconda.html

Make sure you cloned this repository and enter its directory. Then create a Conda environment that will automatically install all of zesje's Python dependencies:

conda env create  # Creates an environment from environment.yml

Then, activate the conda environment:

conda activate zesje-dev

You should see (zesje-dev) inserted into your shell prompt. This tells you that the environment is activated.

Install all of the Javascript dependencies:

yarn install

Unfortunately there is also another dependency that must be installed manually for now (we are working to bring this dependency into the Conda ecosystem). You can install this dependency in the following way on different platforms:

OS	Command
macOS	brew install libdmtx
Debian, Ubuntu	apt install libdmtx-dev
Arch	pacman -S libdmtx
Fedora	dnf install libdmtx
openSUSE	zypper install libdmtx0

Setting up MySQL server

If this is the first time that you will run Zesje with MySQL in development, then run the following command from the Zesje repository directory:

yarn dev:mysql-init

That's all it needs to create the MySQL files in the data directory, migrate the database to the last schema and move all your previous data.

Running a development server

Activate your zesje development environment and run

yarn dev

to start the development server, which you can access on http://127.0.0.1:8881. It will automatically reload whenever you change any source files in client/ or zesje/.

Running Oauth2 Mock Server

By default, login is disabled during development but it can be enabled by setting LOGIN_DISABLED = False in the development configuration file. You can see the set of supported login providers in constants.py but take into account that for GitLab and Surf Conext you will need to request for a valid CLIENT_ID and CLIENT_SECRET.

In case you only want to test the flow, you can set the provider to mock and start the mock oauth server in a different terminal from where you started the development server by running yarn dev:oauth.

Generate sample data

The script example_data.py can be used to create a sample exam that mimics the appearance and behavior of a typical grading process in Zesje. The prototype exam consist on 3 open answer questions per page and 1 multiple choice question per page (excluding the first one). The script partially solves those questions and assigns random feedback to the answered questions while the not answered questions are processed as blank.

The script is called from the command line with the following parameters:

• -d, --delete If specified, removes any existing data and creates a new empty database. Otherwise, new exams are added without deleting previous data.
• --exams (int) the number of exams to add, default is 1.
• --pages (int) the number of pages per exam, default is 3.
• --students (int) the number of students per exam, default is 30
• --graders (int) the number of graders to add, default is 4.
• --solve (float) between 0 and 100, indicates the percentage of questions to answer (including MCQ), default is 90%.
• --grade (float) between 0 and 100, indicate the percentage of solved questions to grade (that is, excluding blank answers), default is 60%.
• --skip-processing if specified, fakes the pdf processing to reduce time. As a drawback, blanks will not be detected.
• --multiple-copies (float) between 0 and 100, indicates how much of the students submit multiple copies, default is 5%

The actual processing of the exam takes a while, specially when the number of students is large.

Running the tests

You can run the tests by running

yarn test

Viewing test coverage

As a test coverage tool for Python tests, pytest-cov is used.

To view test coverage, run

yarn test:py:cov

A coverage report is now generated in the terminal, as an XML file, and in HTML format. The HTML file shows an overview of untested code in red.

Viewing coverage in Visual Studio Code

There is a plugin called Coverage Gutter that will highlight which lines of code are covered. Simply install Coverage Gutter, after which a watch button appears in the colored box at the bottom of your IDE. When you click watch, green and red lines appear next to the line numbers indicating if the code is covered.

Coverage Gutter uses the XML which is produced by yarn test:py:cov, called cov.xml. This file should be located in the main folder.

Viewing coverage in PyCharm

To view test coverage in PyCharm, run yarn test:py:cov to generate the coverage report XML file cov.xml if it is not present already.

Next, open up PyCharm and in the top bar go to Run -> Show Code Coverage Data (Ctrl + Alt + F6).

Press + and add the file cov.xml that is in the main project directory. A code coverage report should now appear in the side bar on the right.

Policy errors

If you encounter PolicyErrors related to ImageMagick in any of the previous steps, please try the instructions listed here as a first resort.

Database modifications

Zesje uses Flask-Migrate and Alembic for database versioning and migration. Flask-Migrate is an extension that handles SQLAlchemy database migrations for Flask applications using Alembic.

To change something in the database schema, simply add this change to zesje/database.py. After that run the following command to prepare a new migration:

yarn dev:prepare-migration

This uses Flask-Migrate to make a new migration script in migrations/versions which needs to be reviewed and edited. Please suffix the name of this file with something distinctive and add a short description at the top of the file. To apply the database migration run:

yarn dev:mysql-migrate # (for the development database)
yarn migrate # (for the production database, MySQL must be running)

Building and running the production version

Code style

Python

Adhere to PEP8, but use a column width of 120 characters (instead of 79).

If you followed the instructions above, the linter flake8 and the formatter black are installed in your virtual environment. If you use Visual Studio Code, install the Python extension and add the following lines to your workspace settings:

"python.linting.pylintEnabled": false,
"python.linting.flake8Enabled": true,
"[python]": {
    "editor.rulers": [120],
    "editor.defaultFormatter": "ms-python.black-formatter",
    "editor.formatOnSave": true
},
"black-formatter.args": [
    "--line-length=120"
]

If you use Atom, install the linter-flake8 plugin and add the following lines to your config:

".source.python":
  "editor":
    "preferredLineLength": 120

Javascript

Adhere to StandardJS.

If you use Visual Studio Code, install the ESLint plugin.

If you use Atom, install the linter-eslint plugin.

Adding dependencies

Server-side

If you start using a new Python library, be sure to add it to environment.yml. The packages can be installed and updated in your environment by conda using

conda env update

Client-side

Yarn keeps track of all the client-side dependancies in package.json when you install new packages with yarn add [packageName]. Yarn will install and update your packages if your run

yarn install

License

Zesje is licensed under AGPLv3, which can be found in LICENSE. An summary of this license with it's permissions, conditions and limitations can be found here.