Example 2: Appointments

SIGCSE 2006 Workshop Companion Web Site

Goal

In this example, we will be using another simple CS1-style problem to introduce you to using instructor-provided "acceptance tests" for grading. For context, imagine that you are going to develop a pair of classes that work together to implement a rudimentary timetable. One class will represent an appointment at a specific time, while another will represent a week-long timetable of appointments.

Note: If you are unable to complete this example, or if you are unfamiliar with Java syntax and need a bit of help, the Appointments-final directory contains completed versions of the source files for this example.

A C++ version of this example is also available.

Learning Objectives

• Exposure to providing pre-compiled acceptance tests
• Familiarity with writing code to meet instructor-provided acceptance tests
• Exposure to using acceptance tests to judge the correctness of student work

Procedure

1. Set up your IDE

   Follow the instructions in Example 1 if you need help. The remainder of these instructions are written for Eclipse users, but should be similar for other environments.

2. Create an Appointment project

   Again, follow the instructions in Example 1 to create an Appointments project consisting of the files in the Appointments directory.

   The Appointments directory also contains a jar file called AcceptanceTests.jar. Add this jar to your project's classpath using whatever mechanism is appropriate for your development environment.

   The AcceptanceTests.jar file contains an instructor-provided set of "hidden" test cases that can be used to assess the correctness of your implementation. In this case, the hidden tests are included in a pre-compiled form in a jar file contained in the project. The AcceptanceSuite class, while empty, provides a convenient handle by which you can execute the hidden test suite.

3. Open the TimeTable.java file

   The TimeTable class holds a two-dimensional array of appointments, indexed by day of the week and hour of the day. Quickly skim the simple methods in this class, which have already been implemented for you.

4. Open the Appointment.java file

   The Appointment class represents a single appointment scheduled at a specific hour of the day. Its basic fields and the corresponding setters and getters have already been implemented for you. Read through the Javadoc comments for the methods to get a feel for how this class is intended to operate.

5. Run the acceptance tests

   Select the AcceptanceSuite.java file in the pane on the left. Use the Run->Run As->JUnit Test menu command to execute the tests (but don't examine the results in detail yet!). In this particular case, although the actual source code for the tests has been hidden, the test case method names and the failure traces have not been disguised. At this point, avoid looking at the detailed test failure information until you've moved a bit farther along. As you may have seen when examining the Appointment class, two of its methods are currently unimplemented, and they are the source of all the failures in this case.

6. Implement Appointment.toString()

   One of the unimplemented methods in the Appointment class is toString(). Read its Javadoc description, and add an implementation for the method.

7. Implement Appointment.setTime()

   The second unimplemented method in the Appointment class is setTime(). Read its Javadoc description, and add an implementation for the method.

8. Re-run the acceptance tests

   Re-run the AcceptanceSuite using the procedure described above. Do all the tests pass? If not, now is the time to examine the failure information in more detail.

9. Fix any errors

   If any acceptance tests have failed, examine the failure trace information and debug the methods you have implemented. Continue to re-run the acceptance tests and debug until they all pass.

Note: While the acceptance test suite in this project is provided as part of the project itself, this is not always convenient. Some of the issues are the ease with which such code can be decompiled, and the difficulty of writing useful, comprehensive tests while preventing JUnit from "giving away" the key concepts in the tests via its test failure information.

As a result, you may consider using some form of automated grading system to automatically assess student code against reference tests. This processing might take place on a server somewhere, so that the critical information can be kept out of reach of students, while still allowing useful feedback to be provided.