Usage

Terminology and conventions

repomate-junit4 adds some additional terminology to Repomate that you need to be familiar with to fully understand the rest of the documentation.

  • Production class: A Java file/class in the student repo (written by the student).
  • Test class: A Java file/class ending in Test.java containing tests for a namesake production class. Test classes are paired with production classes by simply appending Test to the production class name. For example, LinkedList.java would have a test class called LinkedListTest.java.
  • Test directory: A directory named after a master repo, containing tests for the assignments in that repo.
  • Reference tests directory (RTD): A directory containing test directories (as defined above).

See the Example use case for a more detailed look at how all of this fits together.

CLI arguments

repomate-junit4 adds several new CLI arguments to the repomate clone command.

  • -rtd|--reference-tests-dir
    • Path to the RTD.
    • Can be specified in the configuration file with the reference_test_dir option.
    • Required unless specified in the configuration file.
  • -junit|--junit-path
    • Path to the junit-4.12.jar library.
    • Picked up automatically if on the CLASSPATH environment variable.
    • Can be specified in the configuration file with the junit_path option.
    • Required unless specified on the CLASSPATH variable, or in the configuration file.
  • -ham|--hamcrest-path
    • Path to the hamcrest-core-1.3.jar library.
    • Picked up automatically if on the CLASSPATH environment variable.
    • Can be specified in the configuration file with the hamcrest_path option.
    • Required unless specified on the CLASSPATH variable, or in the configuration file.
  • -i|--ignore-tests
    • A whitespace separated list of test files (e.g. LinkedListTest.java) to ignore.
  • --disable-security
    • Disable the security policy.
  • -v|--verbose
    • Display more verbose information (currently only concerns test failures).
    • Long lines are truncated.
  • -vv|--very-verbose
    • Same as -v, but without truncation.

Example use case

Assume that we have a master repo called fibonacci with an assignment to implement a method that returns the n:th Fibonacci number. The master repo could then look like this:

fibonacci
├── README.md
└── src
    └── Fibo.java

To be able to test the students’ implementations, we write a test class FiboTest.java and put it in our reference tests directory, in a test directory named after the master repository. The reference test directory would then look like this.

reference_tests
└── fibonacci
    └── FiboTest.java

Note

I strongly recommend having the reference tests in version control.

Now, assume that we have students ham, spam and eggs, and their student repos ham-fibonacci, spam-fibonacci and eggs-fibonacci. Assuming that the JUnit4 and Hamcrest jars have been configured as suggested in Configuration, and that the basic Repomate arguments are configured (see the Repomate config docs), we can run repomate clone with repomate-junit4 activated like this:

$ repomate -p junit4 clone -mn fibonacci -s ham spam eggs -rtd /path/to/reference_tests
[INFO] cloning into student repos ...
[INFO] Cloned into https://some-enterprise-host/some-course-org/inda-18/ham-fibonacci
[INFO] Cloned into https://some-enterprise-host/some-course-org/inda-18/spam-fibonacci
[INFO] Cloned into https://some-enterprise-host/some-course-org/inda-18/eggs-fibonacci
[INFO] executing post clone hooks on repos
[INFO] executing post clone hooks on eggs-fibonacci
[INFO] executing post clone hooks on spam-fibonacci
[INFO] executing post clone hooks on ham-fibonacci
[INFO]
hook results for spam-fibonacci

junit4: SUCCESS
Status.SUCCESS: Test class FiboTest passed!


hook results for eggs-fibonacci


junit4: ERROR
Status.ERROR: multiple production classes found for FiboTest.java


hook results for ham-fibonacci

junit4: ERROR
Status.ERROR: Test class FiboTest failed 1 tests


[INFO] post clone hooks done

Note

The output is color coded when displayed in a terminal.

Let’s digest what happened here. We provided the master repo name (-mn fibonacci) and the reference tests directory (-rtd /path/to/reference_tests). repomate-junit4 then looked in the test directory matching the master repo name (i.e. fibonacci) test directory and found a test class FiboTest.java. By the naming convention, it knows that it should now look for a file called Fibo.java in the student repos. The following then happened when testing the repos:

  • spam-fibonacci: The production class Fibo.java was found and passed the test class.
  • eggs-fibonacci: Multiple files called Fibo.java were found, and repomate-junit4 did not know which one to use. - Duplicate class names are only allowed if their fully qualified names differ (i.e. the classes are in different packages). If production code is supposed to be packaged, the test classes must also be packaged (in the same package).
  • ham-fibonacci: The production class Fibo.java was found, but failed one of the tests. - Running the same command again with -v or -vv would display which test failed, and why.

Other common causes of errors include:

  • No production class found for a test class.
  • Compile error.
  • Security policy violation.

This concludes the use case example, I hope you found it enlightening.