|
| 1 | + |
| 2 | +# Jacquard FAQ |
| 3 | +* [How do I make sure I have the latest version of the Jacquard library?](https://github.com/jacquard-autograder/jacquard-examples/blob/main/README.md#how-do-i-make-sure-i-have-the-latest-version-of-the-jacquard-library) |
| 4 | +* [What configuration options are there?](https://github.com/jacquard-autograder/jacquard-examples/blob/main/README.md#what-configuration-options-are-there) |
| 5 | +* [How do I use Checkstyle?](https://github.com/jacquard-autograder/jacquard-examples/blob/main/README.md#how-do-i-use-checkstyle) |
| 6 | +* [What's PMD? How do I use it?](https://github.com/jacquard-autograder/jacquard-examples/blob/main/README.md#whats-pmd-how-do-i-use-it) |
| 7 | +* [How do I set test result visibility?](https://github.com/jacquard-autograder/jacquard-examples/blob/main/README.md#how-do-i-set-test-result-visibility) |
| 8 | +* [Why was the name "Jacquard" chosen?](https://github.com/jacquard-autograder/jacquard-examples/blob/main/README.md#why-was-the-name-jacquard-chosen) |
| 9 | + |
| 10 | +## How do I make sure I have the latest version of the Jacquard library? |
| 11 | + |
| 12 | +See [Refreshing the Jacquard library](https://northeastern.hosted.panopto.com/Panopto/Pages/Viewer.aspx?id=8578e267-2bf0-4849-94c0-b066015c1ee3) |
| 13 | +or follow these steps in IntelliJ: |
| 14 | + |
| 15 | +1. Click on `Gradle` in the right sidebar. |
| 16 | +2. Right-click (or control-click) on the project name (or the elephant icon to its left). |
| 17 | +3. Select `Refresh Gradle Dependencies`. |
| 18 | + |
| 19 | + |
| 20 | + |
| 21 | +## What configuration options are there? |
| 22 | +There are currently 3 configurable values: |
| 23 | +* `timeout` (default: `10_000L`), how many milliseconds to run a test before termination; |
| 24 | + a value of `0` means never to timeout |
| 25 | +* `javaLevel` (default: 17), the Java language level used for [syntax-based graders](https://jacquard.ellenspertus.com/com/spertus/jacquard/syntaxgrader/package-summary.html) |
| 26 | +* `visibility` (default: [`Visibility.VISIBLE`](https://jacquard.ellenspertus.com/com/spertus/jacquard/common/Visibility.html#VISIBLE)), |
| 27 | + the visibility of test results (except for `JUnitTester` results, which are specified differently) |
| 28 | + |
| 29 | +To use the default values, call [`Autograder.init()`](https://jacquard.ellenspertus.com/com/spertus/jacquard/common/Autograder.html#init()) |
| 30 | +at the start of your program. Here's how to explicitly set other values: |
| 31 | + |
| 32 | +```java |
| 33 | +Autograder.Builder builder = Autograder.Builder.getInstance(); |
| 34 | + |
| 35 | +// By default, tests time out in 10,000 ms if they don't complete. |
| 36 | +builder.timeout(5000); // set timeout to 5 s |
| 37 | + |
| 38 | +// By default, Java level 17 is used. |
| 39 | +builder.javaLevel(11); // use Java level 11 |
| 40 | + |
| 41 | +// By default, all tests results are visible. |
| 42 | +builder.visibility(Visibility.HIDDEN); // hide test results |
| 43 | +builder.build(); |
| 44 | +``` |
| 45 | +This can be written more concisely: |
| 46 | +``` |
| 47 | +Autograder.Builder.getInstance() |
| 48 | + .timeout(5000) |
| 49 | + .javaLevel(11) |
| 50 | + .visibility(Visibility.HIDDEN) |
| 51 | + .build(); |
| 52 | +``` |
| 53 | + |
| 54 | +See also the [Autograder configuration chapter](https://northeastern.hosted.panopto.com/Panopto/Pages/Viewer.aspx?id=ba36573d-dd4a-493d-8b3d-b06a0181c9ff&start=15) (0:15-2:06) from [Taking a first look at Homework 1](https://northeastern.hosted.panopto.com/Panopto/Pages/Viewer.aspx?id=ba36573d-dd4a-493d-8b3d-b06a0181c9ff). |
| 55 | + |
| 56 | +## How do I use Checkstyle? |
| 57 | + |
| 58 | +For general usage information, see [Checkstyle website](https://checkstyle.sourceforge.io/), |
| 59 | +especially [Checkstyle configuration](https://checkstyle.sourceforge.io/config.html). |
| 60 | + |
| 61 | +Here is how to create a `CheckstyleGrader` in Jacquard: |
| 62 | + |
| 63 | +```java |
| 64 | +CheckstyleGrader checkstyleGrader = new CheckstyleGrader( |
| 65 | + "config/checkstyle-rules.xml", // path to configuration file |
| 66 | + 1.0, // penalty per violation |
| 67 | + 5.0); // maximum penalty/points |
| 68 | +``` |
| 69 | + |
| 70 | +See also the [`CheckstyleGrader` javadoc](http://jacquard.ellenspertus.com/com/spertus/jacquard/checkstylegrader/CheckstyleGrader.html). |
| 71 | + |
| 72 | +We recommend putting your configuration file in your project's `config/` |
| 73 | +directory so it is copied to Gradescope. We also recommend sharing it with |
| 74 | +students so they can run checkstyle in their |
| 75 | +IDE ([IntelliJ plugin](https://plugins.jetbrains.com/plugin/1065-checkstyle-idea), |
| 76 | +[Eclipse plugin](https://checkstyle.org/eclipse-cs/#!/)) |
| 77 | +before uploading. The IntelliJ plugin supports using a local configuration |
| 78 | +file or accessing one via URL, so students don't need to download it |
| 79 | +(but will need to configure the plugin to point to it). |
| 80 | + |
| 81 | +For more detail, see |
| 82 | +[Jacquard Example 0](https://github.com/jacquard-autograder/jacquard-example0). |
| 83 | + |
| 84 | +## What's PMD? How do I use it? |
| 85 | +[PMD](https://pmd.github.io/) (which is not an acronym) is a source code analyzer |
| 86 | +capable of more complex checks than Checkstyle, such as whether the `@Override` |
| 87 | +annotation is always used where permitted. |
| 88 | + |
| 89 | +PMD rules are organized into rulesets, which, as the name suggests, are sets of rules. |
| 90 | +You can [make your own rulesets](https://pmd.github.io/pmd/pmd_userdocs_making_rulesets.htm) |
| 91 | +or use [Java rulesets](https://github.com/pmd/pmd/tree/master/pmd-java/src/main/resources) |
| 92 | +built in to PMD, such as [`category/java/bestpractices.xml`](https://github.com/pmd/pmd/blob/master/pmd-java/src/main/resources/category/java/bestpractices.xml). |
| 93 | + |
| 94 | +Jacquard's [PMDGrader](https://jacquard.ellenspertus.com/com/spertus/jacquard/pmdgrader/PmdGrader.html) |
| 95 | +has two static factory methods: |
| 96 | +* [`createFromRuleSetPaths()`](http://jacquard.ellenspertus.com/com/spertus/jacquard/pmdgrader/PmdGrader.html#createFromRuleSetPaths(double,double,java.lang.String...)), |
| 97 | + which lets you specify one or more rulesets to be used in their entirety [used in [Jacquard Example 0](https://github.com/jacquard-autograder/jacquard-example0)] |
| 98 | +* [`createFromRules()`](http://jacquard.ellenspertus.com/com/spertus/jacquard/pmdgrader/PmdGrader.html#createFromRules(double,double,java.lang.String,java.lang.String,java.lang.String...)), |
| 99 | + which lets you specify one ruleset and one or more rules from that ruleset [used in Jacquard Example 2] |
| 100 | + |
| 101 | +There are PMD plugins for [IntelliJ](https://plugins.jetbrains.com/plugin/1137-pmd) and [Eclipse](https://marketplace.eclipse.org/category/free-tagging/pmd). |
| 102 | + |
| 103 | +## How do I set test result visibility? |
| 104 | + |
| 105 | +Gradescope specifies four levels of visibility in [Autograder Specifications](https://gradescope-autograders.readthedocs.io/en/latest/specs/): |
| 106 | + |
| 107 | +* `hidden`: test case will never be shown to students |
| 108 | +* `after_due_date`: test case will be shown after the assignment's due date has passed. If late submission is allowed, then test will be shown only after the late due date. |
| 109 | +* `after_published`: test case will be shown only when the assignment is explicitly published from the "Review Grades" page |
| 110 | +* `visible` (default): test case will always be shown |
| 111 | + |
| 112 | +These is a one-to-one correspondence between these visibility levels and the enumerated type [`Visibility`](http://jacquard.ellenspertus.com/com/spertus/jacquard/common/Visibility.html). |
| 113 | + |
| 114 | +Unless otherwise specified, all test results are immediately `visible` to students. |
| 115 | + |
| 116 | +### `JUnitTester` results |
| 117 | +Unit tests run through [`JUnitTester`](https://jacquard.ellenspertus.com/com/spertus/jacquard/junittester/JUnitTester.html) (as |
| 118 | +opposed to the cross-tester) must be annotated with [`@GradedTest`](https://jacquard.ellenspertus.com/com/spertus/jacquard/junittester/GradedTest.html). The |
| 119 | +attribute `visibility` has the default value [`Visibility.VISIBLE`](https://jacquard.ellenspertus.com/com/spertus/jacquard/common/Visibility.html#VISIBLE) but |
| 120 | +can be set to any other visibility. This code is from [Jacquard Example 0](https://github.com/jacquard-autograder/jacquard-example0): |
| 121 | +```java |
| 122 | + @Test |
| 123 | + @GradedTest(name = "works for empty list", points = 5.0, visibility = Visibility.AFTER_PUBLISHED) |
| 124 | + public void iteratorOverEmptyList() { |
| 125 | + FavoritesIterator<String> iterator = new FavoritesIterator<>(favoriteHotSauces0); |
| 126 | + |
| 127 | + // No items should be returned. |
| 128 | + assertFalse(iterator.hasNext()); |
| 129 | + assertThrows(NoSuchElementException.class, () -> iterator.next()); |
| 130 | + } |
| 131 | +``` |
| 132 | + |
| 133 | +### Other results |
| 134 | +The visibility level can be set for all other types of autograder results through the |
| 135 | +[initial configuration](https://github.com/jacquard-autograder/jacquard-examples/blob/main/README.md#what-configuration-options-are-there). |
| 136 | + |
| 137 | +The visibility level of a generated [`Result`](https://jacquard.ellenspertus.com/com/spertus/jacquard/common/Result.html) can be mutated by calling the [`changeVisibility(Visibility visibility)` instance method](https://jacquard.ellenspertus.com/com/spertus/jacquard/common/Result.html#changeVisibility(com.spertus.jacquard.common.Visibility)) or [`Result.changeVisibility(List<Result> results, Visibility visibility)`](https://jacquard.ellenspertus.com/com/spertus/jacquard/common/Result.html#changeVisibility(java.util.List,com.spertus.jacquard.common.Visibility)), as shown: |
| 138 | + |
| 139 | +```java |
| 140 | + // Use the default configuration, which includes full visibility. |
| 141 | + Autograder.init(); |
| 142 | + final Target target = Target.fromClass(FavoritesIterator.class); |
| 143 | + List<Result> results = new ArrayList(); |
| 144 | + |
| 145 | + // Checkstyle results should be fully visible. |
| 146 | + CheckstyleGrader checkstyleGrader = new CheckstyleGrader( |
| 147 | + "config/checkstyle-rules.xml", |
| 148 | + 1.0, |
| 149 | + 5.0); |
| 150 | + results.addAll(checkstyleGrader.grade(target)); |
| 151 | + |
| 152 | + // PMD results should be visible only after the due date. |
| 153 | + PmdGrader pmdGrader = PmdGrader.createFromRules( |
| 154 | + 1.0, |
| 155 | + 5.0, |
| 156 | + "category/java/bestpractices.xml", |
| 157 | + "MissingOverride"); |
| 158 | + List<Result> pmdResults = pmdGrader.grade(target); |
| 159 | + // Change visibility before adding to results. |
| 160 | + Result.changeVisibility(pmdResults, Visibility.AFTER_DUE_DATE); |
| 161 | + results.addAll(pmdResults); |
| 162 | +``` |
| 163 | + |
| 164 | +## Why was the name "Jacquard" chosen? |
| 165 | + |
| 166 | +The CSV files used for cross-testing made me think of looms, such as the [looms created by |
| 167 | +Joseph Marie Jacquard](https://en.wikipedia.org/wiki/Jacquard_machine), which were |
| 168 | +controlled by punched cards so play an important role in computing history. Also, the |
| 169 | +starting letters correspond to Java or Java Autograder. Claude.ai suggested |
| 170 | +this backronym: _Java Assignment Checking with Quality Unit-testing, Analysis, Reporting, and Diagnostics_. |
| 171 | + |
| 172 | + |
| 173 | +## Where can I get support? |
| 174 | + |
| 175 | +There are low-volume Google |
| 176 | +groups [jacquard-announce](https://groups.google.com/g/jacquard-announce) |
| 177 | +and [jacquard-discuss](https://groups.google.com/g/jacquard-discuss). |
| 178 | + |
| 179 | +You can also [create issues](https://github.com/jacquard-autograder/jacquard/issues) |
| 180 | +(feature requests and bug reports). |
| 181 | + |
| 182 | +[](https://jacquard.ellenspertus.com/) |
0 commit comments