Unit Testing

In this example project, we’ll go through the steps of creating unit tests for an existing project. This is a great example of white-box testing since we’ll have access to the source code of the application. As we are developing our tests, we’ll also improve the code of the application itself as we find some errors and edge cases that it doesn’t handle very well.

The next page will discuss the overall requirements that this example project should include. After that, there is a page for each programming language with some basic steps and a video to walk you through the whole process.

For these example projects, you’ll be given some starter code via the GitHub Classroom assignment, so make sure you’ve accepted the assignment and created your repository in GitHub first.

Good luck!

Subsections of Unit Testing

Assignment Requirements

This page lists the example project requirements for Example 3 in CC 410. Read the requirements carefully and discuss any questions with the instructors or TAs.

Purpose

This example will cover creating adding unit tests to an existing project. For this example, we’ll focus on a simple guessing game.

General Requirements

Warning

The first couple of milestones only require a subset of the general requirements introduced in the “Hello Real World” project. Read this section carefully to see what is required for this particular milestone.

This milestone must follow these professional coding standards:

  • All code must be object-oriented.
    • All executable code must be within a class
      • Python package files such as __init__.py and __main__.py are exempt.
    • Classes must be organized into packages based on common usage.
  • This project must include automation for compilation, unit testing, documentation generation, and execution.
    • Java: Use Gradle with the application plugin. The project should compile without errors. You may include a main class in a separate package for testing purposes only.
    • Python: Use tox configured to use Python 3.10 and a requirements file to install libraries. You may include a main class in a separate package for testing purposes only.
  • All code must properly compile or be interpreted.
    • Java: It must compile using Gradle.
    • Python: It must be interpreted using Python 3.10. Where specified, type hints should be included in the code, and all code should pass a strict Mypy type check.
  • Where specified, code should contain appropriate unit tests that achieve the specified level of code coverage.
    • Java: Use JUnit 5. You may choose to use Hamcrest for assertions.
    • Python: Use pytest. You may choose to use Hamcrest for assertions.
  • Where specified, code should contain appropriate documentation comments following the language’s style guide.
    • Java: Use javadoc to generate documentation.
    • Python: Use pdoc3 to generate documentation.
  • Submissions to Canvas should be tagged GitHub releases that are numbered according to Semantic Versioning.

The following requirements ARE NOT enforced for this milestone, but will be enforced in later milestones that use the same code. We will focus on learning to meet each of these requirements in future modules. However, you are welcome to “plan ahead” by minimizing the number of style errors in your code and adding some basic documentation where desired.

Naming Standards

You can make things easier on yourself by following proper naming standards for your language of choice, even though we aren’t enforcing a style guide for this milestone.

  • Java - All names are in CamelCase. Classes start with uppercase, like ClassName, methods and attributes start with lowercase like methodName. See the Google Style Guide.
  • Python - All names are lowercase with underscores like method_name, with the exception of classes, which are named in CamelCase starting with an uppercase letter like ClassName. See the Google Style Guide.

It is easier to get this correct from the start, then having to refactor your code later. Of course, major refactoring is also a good lesson that guarantees you’ll get it right in the future!

  • (Milestone 3) All code submitted must be free of style errors. We will be using the Google Style Guide for each language.
    • Java: Use Checkstyle 10.6.0+ and the Google Style Configuration.
      • You may modify the configuration to allow 4 space indentations instead of 2 space indentations.
    • Python: Use Flake8 with the flake8-docstrings and pep8-naming plugins. Code should conform to PEP 8 style with Google style docstrings.

Assignment Requirements

This milestone should include the following features:

  • Complete Unit Tests for the GuessingGame class that achieve 100% code coverage and adequately test all aspects of the code.
  • Update GuessingGame class to use an enumeration as a return value in the guess method.
  • Update GuessingGame to properly handle punctuation, uppercase and lowercase, and require a minimum length for the secret.
  • Complete documentation comments in all code files. Checkstyle or Flake8 should not report any missing documentation.
  • Create a README.md file in the root of the project, and describe unit tests you feel should be added to the example to cover untested aspects of GuessingGame. You do not have to write the tests, just discuss aspects you feel are not adequately tested by the tests covered in the video.
  • Create a UML Class Diagram for the entire GuessingGame program (just the source code, you may omit the unit tests). Store the diagram in the root of the project next to README.md as an image file (PNG preferred). You may also wish to include any other files used to create the diagram.

Time Requirements

Completing this project is estimated to require 1 hour.

Grading Rubric

This assignment will be graded based on the rubric below:

  • Updates to GuessingGame class - 10%
  • Unit Tests - 40%
  • Documentation - 30%
  • README.md file discussing additional tests - 10%
  • UML Class Diagram - 10%

The following deductions apply:

  • Any portion of the project which will not compile (Java), pass a strict type check (Python), or execute properly will be given a grade of 0.

This is not an exhaustive list of possible deductions. The instructors will strive to provide reasonable and fair grading, but we can’t predict all possible defects. It is up to the student to ensure that the project is complete and correct before submission.

Submission

Submit this assignment by creating a release on GitHub and uploading the release URL to the assignment on Canvas. You should not submit this Codio project or mark it as complete in Codio, in case you need to come back to it and make changes later.

Java

YouTube Video

Resources

Gradle Changes

In the build.gradle file, the JUnit 5 parameters library was added:

dependencies {
    // Use JUnit Jupiter API for testing.
    testImplementation 'org.junit.jupiter:junit-jupiter-api:5.6.2', 'org.hamcrest:hamcrest:2.2', 'org.junit.jupiter:junit-jupiter-params'

    // Use JUnit Jupiter Engine for testing.
    testRuntimeOnly 'org.junit.jupiter:junit-jupiter-engine'

    // This dependency is used by the application.
    implementation 'com.google.guava:guava:29.0-jre'
}

Also, we added a quick section at the bottom to allow Gradle tasks to read input from System.in:

// Allow run to read from System.in
run{
    standardInput = System.in
}

Outline

Here is a basic outline of the steps to follow to complete this example.

  1. Clone Starter Code from GitHub
git clone <url> java
  1. Install SDKMAN

Instructions

curl -s "https://get.sdkman.io" | bash

  1. Close and Reopen Terminal to load SDK Man

  2. Install Gradle

sdk install gradle 7.6
  1. Compile, Run & Test Existing Project
cd java
gradle run
gradle test
gradle check
gradle javadoc

  1. Confirm that project runs, no style errors, and Javadoc generates properly.

  2. Create New Unit Tests and Update Code as Needed. Continuously commit to Git as changes are made!

  3. Add Documentation Comments. Continuously commit to Git as changes are made!

  4. Add README.md and discuss unit tests you feel should be added to adequately test the GuessingGame class.

  5. Create a UML Class Diagram for the source code and include it in the project.

  6. Confirm that project runs, no style errors related to comments, and Javadoc generates properly.

  7. When complete, use Git to commit and push updated code.

git add .
git commit -m "Example Complete"
git push
  1. On GitHub, create a release tag and submit URL to Canvas for grading.

Python

YouTube Video

Resources

Tox Changes

In the tox.ini file, we added the following line under the [testenv] heading:

ignore_errors = True

This will allow the full Tox script to execute, even if there are errors earlier in the process.

Outline

Here is a basic outline of the steps to follow to complete this example.

  1. Clone Starter Code from GitHub
git clone <url> python
  1. Run Project
cd python
python3 -m src
  1. Install Tox
pip3 install tox
  1. Check & Test Existing Project
python3 -m tox

  1. Confirm that project runs, all unit tests pass, no style errors, no type errors, and documentation generates properly.

  2. Create New Unit Tests and Update Code as Needed. Continuously commit to Git as changes are made!

  3. Add Documentation Comments. Continuously commit to Git as changes are made!

  4. Add README.md and discuss unit tests you feel should be added to adequately test the GuessingGame class.

  5. Create a UML Class Diagram for the source code and include it in the project.

  6. Confirm that project runs, no style errors related to comments, and pydoc3 generates properly.

  7. When complete, use Git to commit and push updated code.

git add .
git commit -m "Example Complete"
git push
  1. On GitHub, create a release tag and submit URL to Canvas for grading.

6.0.0

Last modified by: Russell Feldhausen Sep 8, 2021