purduecsbridge / percolator

:hotsprings: Java grading framework for Gradescope and Vocareum

Percolator

Percolator is a grading framework for Java programming assignments on Gradescope and Vocareum. It is meant to make the development and maintenance of programming assignments easier for courses using Java. How easy is it?

import edu.purdue.cs.percolator.TestCase;

import org.junit.Test;

public class HelloWorldTests {

    @Test(timeout = 1000)
    @TestCase(name = "Hello test", points = 50.0)
    public void testHello() {
        // Test code here
    }
  
    @Test(timeout = 1000)
    @TestCase(name = "Goodbye test", points = 50.0)
    public void testGoodbye() {
        // Test code here
    }

}

That's a test suite written using Percolator. Pretty simple, right? Call the AutoGrader.run() method to run your test suites and automatically print the results in JSON for Gradescope.

import edu.purdue.cs.percolator.AutoGrader;

public class TestRunner {

    public static void main(String[] args) {
        String[] testSuites = {HelloWorldTests.class, DebuggingTests.class};
        AutoGrader.grade(testSuites).run();
    }

}

You can customize the settings for the AutoGrader using its builder methods, including adding a code style checker.

import edu.purdue.cs.percolator.AutoGrader;
import edu.purdue.cs.percolator.StyleChecker;

public class TestRunner {

    public static void main(String[] args) {
        String[] testSuites = {TestSuiteOne.class, TestSuiteTwo.class};
        StyleChecker codeStyleChecker = StyleChecker.lint(
                "/autograder/submission", "/autograder/source/checkstyle.xml")
                .withMaxScore(5.0)
                .withDeduction(1.0);
        AutoGrader.grade(testSuites)
                .withMaxScore(95.0)
                .withStyleChecker(codeStyleChecker)
                .run();
    }

}

The StyleChecker audits the Java source files in a given directory and enforces the rules defined in a Checkstyle configuration.

By default, the AutoGrader will assume you are using Gradescope. If you are using Vocareum instead, just use the onVocareum() method when constructing your AutoGrader.

import edu.purdue.cs.percolator.AutoGrader;

public class TestRunner {

    public static void main(String[] args) {
        String[] testSuites = {TestSuiteOne.class, TestSuiteTwo.class};
        AutoGrader.grade(testSuites)
                .onVocareum()
                .run();
    }

}

Percolator also includes a number of utilities that make writing test cases easier. To see how we use these utilities in our test cases, take a look at our lab examples.

Installation

Instructions on how to add Percolator to your Maven project can be found here.

Contributing

Pull requests and new issues are always welcome.

License

Licensed under the MIT License.