P3: JUnit
40 points
Due September 29, 2016

1. Overview

This assignment must be done as a team using GitHub. The goal is to develop a small application using Test Driven Development; you will write JUnit test cases to "specify" the behavior of the implementation and also write Java code for the implementation. Finally you will measure code coverage for your test cases.

Note that we are building your skillset. In P2 you learned to use GitHub. In P3 you will learn to use JUnit while working with GitHub. This will get you ready for the chat project where you will be adding new features, writing test cases, as well as using GitHub.


2. Description

This description has been adapted from a previous assignment written by Ken Shrum, who used to teach a class at Colorado State University in the past.

Certain games use a rectangular grid for the world, and allow the world to "wrap" from top to bottom and from left to right.  Conceptually, this makes a doughnut-shaped world: if you keep going "North" you eventually wrap back around to where you were, and if you keep going "East" you similarly wrap back around.  Note that going North is the +y direction, and going East is the +x direction. We're going to implement a couple of classes to hide the details of the representation from client code.

2.1. World

World represents an n*m grid of Objects, where the coordinates wrap as described above. Note that these Objects refer to instances of the class java.lang.Object.

2.2 Coordinate

Coordinate represents an x,y position in a particular 2D world (where x and y are ints).  The x,y in a Coordinate must always be valid, i.e. in the 0..n-1, 0..m-1 space

Remember that you're doing test-first development. Write a unit test first, then write the code that will pass it. Iterate on this. You'll turn in your test code in addition to the code for World and Coordinate classes.

Any object can be stored in the grid. For testing purposes, feel free to choose something that is simple to compare with the expected object returned by a get method. For example, you can use instances of Integer or String.


3. Tasks

We have created a Java project containing a package called cs314.p3 that consists of two empty classes (World.java and Coordinate.java). This project has been provided in your team's GitHub repository. You will use Git from the command line to pull the code into your local Eclipse environment.

3.1. Set up Git

  1. In Eclipse go to Window→Preferences→Team→Git and look at the Default Repository Folder. It's most likely "$HOME/git" unless you changed it.

  2. In a terminal window, cd <Default repository folder>.

  3. Go to your repository directory: cd cs314_xx, where xx refers to your team number 01, 02, 03, etc.

  4. This directory should contain three sub-directories:

  5. Pull the remote repository:

  6. Now the directory should also have P3 in it.

3.2. Add Project to Eclipse

The following steps tell you how to add the project to Eclipse.
  1. Open Eclipse and go to File→Import.

  2. Choose Git→Projects from Git, then NEXT.

  3. In the "Select Repository" source window, choose Existing Local Repository.

  4. In the "Select a Git Repository" window, choose cs314_xx.

  5. In the "Select a wizard to use for importing projects" window, click the "Import existing Eclipse projects" radio button.

  6. Select P3.

  7. In the "Import Projects" window, P3 should be checked. If not, check only P3.

  8. P3 will be imported as a new project and will be associated with your cs314_xx repository.

3.3. Implement the Code and Test Cases

Once the project is in your Eclipse workspace, you will perform the following tasks.

  1. Create the following four classes according to the description following the class list. (4X7 = 28 points)
    1. WorldTest.java: Contains JUnit tests for the class called World.
    2. World.java: Contains the implementation for the class called World.
    3. CoordinateTest.java: Contains JUnit tests for the class called Coordinate.
    4. Coordinate.java: Contains the implementation for the class called Coordinate.

  2. Create a class called TestAll in the file TestAll.java that defines the test suite containing all the test classes that you have written. (2 points)

3.4. Measure Code Coverage Obtained by Your Test Cases

  1. Install EclEmma:
    1. Go to Help -> Install New Software...
    2. Click on Add...
    3. Enter location: http://update.eclemma.org/ name : EclEmma Update Site and click ok.
    4. After clicking it will take some time to EclEmma plugin appear in the text box.
    5. Click Select All and then Next.
    6. Click next, accept license agreement and client Finish. Ignore the security warning and restart eclipse.

  2. Use EclEmma:
    1. Select project P3.
    2. At the top where you have the Play buttons for running programs, click on the down-arrow next to the play button that has a red and green rectangle on the bottom-left of the play button.
    3. You can run the project as JUnit or as Java Application.
    4. You should be able to view Coverage in the view Console. You can expand the package in the console and view coverage for individual files. If you run multiple times as you add test cases, you can view new coverage by selecting the sessions from a dropdown menu (the one with gears).
    5. You can also right click on project P3, and select Properties. Click on Coverage to see a summary of various types of coverage.
    6. The code view will show colors indicating which parts of the code are covered (or not).
      • green for fully covered lines
      • yellow for partly covered lines
      • red for lines that have not been executed at all
  3. Prepare Coverage Report
    (5 points) Copy the coverage numbers as part of the report.

To get full points for this part, you must do the following:

  1. Your implementation code and test code must compile.
  2. Your tests must pass on your own implementation. If you notice that a test fails, don't remove the test. Instead fix your implementation.
  3. Your implementation must pass our tests.
  4. Your tests must find the faults we have seeded in our own implementation.
  5. You must have written several test cases that use the strategies discussed in class (equivalence classes and boundary values). Your test code should use a variety of JUnit assertions.
  6. Each test case method should test only one aspect. Do not make your test method too long; that's an indication that a test case is trying to test for multiple aspects.


4. Appropriate Use Of GitHub (5 points)

To get full points for this part:

5. Submission

You will submit the following items for this project via canvas, one submission per team.
  1. CR.pdf: Coverage report
  2. P3.jar: Export P3 as a jar file preserving the structure and including only Java source files.