SE 3800, Assignment 2
Writing Your Own Google Tests

This assignment gives you practice at writing maintainable, testable code and developing a carefully written, automated test suite. It assumes you have set up your computer to run Docker as discussed in assignment 1. For this assignment, you will write your own code and construct a Google test suite for that code. You will use this to set up a "pipeline" in the next assignment.

To enable Google Test in your Ubuntu image, you need to execute the commands that are in the Dockerfile from assignment 1: Start your Ubuntu image, open the list of applications, and run Software Updater. This will look for updates and attempt to install them. You can do the same thing from the command prompt by opening a Terminal window and typing

but running Software Updater is more robust. Once the system is up-to-date, type

        sudo apt install -y g++ cmake git libgtest-dev
        cd /usr/src/gtest
        sudo cmake CMakeLists.txt
        sudo make
        sudo cp lib/*.a /usr/lib

(Note: if the last step fails, try sudo cp *.a /usr/lib. If that fails, ask for help.)

Once you have Google Test set up, cd to the directory containing your cube code (cd ~/cube) and type

        make
        ./cube_test

to confirm the tests build and pass.

Using the cube code as an example, write your own program that classifies triangles by the angles entered by a user. All data is entered as floats. The triangles are classified as right, equilateral, isosceles, acute, obtuse, or not a triangle. The 'not a triangle' classification applies whenever the angles do not add to 180. For this and all other rules, use 10^-4 as the tolerance; that is, all matches must be within one part of ten thousand. For legal triangles, the 'right' classification applies whenever one angle is within the tolerance of 90 degrees, and the equilateral classification applies if the angles are (nearly the) same, and the isosceles classification applies if it is not a right triangle and two angles are (nearly) the same. Acute and obtuse apply only when none of the other categories apply and (for acute) all angles are (significantly) less than 90 or (for obtuse) one angle is (significantly) greater than 90. To understand why tolerances are necessary with floating-point values, see ../../samples/crazy-math.cpp.

A naive implementation would be a single main that prompts for the input and writes the results. That is not very testable: it requires you to do various back-flips to capture standard output from test code. A far simpler mechanism is to write functions (and classes in some cases, though probably not for this assignment) that compute the results and returns them as a reference parameter of function result. You can then write main to call these functions and display the results. The wins of this method:

• You can use unit testing to confirm the basic algorithm works on all of the cases.
• Your function can take numeric constants as inputs rather than requiring that they also convert strings along with computing results. Separating reading/converting data from computations is important.

Break your solution into multiple functions that support testing. Your main should be so simple that the only testing needed is to ensure it handles a single common case. You can do that testing at the command prompt (by hand) rather than attempting to automate it through GoogleTest.

The goal of this assignment is to get some experience at writing your own code and tests using the Google framework, not to make you an expert with Google Test. However, there is one common mistake that should be addressed: comparing to true or false is always a bad idea. Use EXPECT_TRUE and EXPECT_FALSE instead of EXPECT_EQ(true, xyz). For example:

        EXPECT_TRUE(is_prime(23));
        EXPECT_FALSE(is_prime(100));

For more detail on Google Test, see this article. It is a quick read and explains the Google Test framework in more detail for those who are looking for more information.

Do's and Don'ts

• Do rename your source files to not reference "cube". This is a different program and it would be very confusing to find a "cube_test.cpp" (say) in a project that classifies triangles.
• Do use lower case names with no spaces for all filenames. Java is about the only language that encourages upper case filenames, and all-lower-case filenames is both more common in the C++ world and a requirement for this course.
• Do separate the code that computes and displays results from the code you write for testing. It should be possible to distribute your project as a library, holding back the test code for internal development only. How you prompt for the data is up to you, but it would be helpful if there was a prompt so your instructor knows what to enter if they run it for themselves. You can either write it to take a single set of numbers and print a result or to loop until the user enters a negative number. In any case, automated tests should never write directly to standard output.
• Do not use arbitrary numbers like 1, 2, and 3 to indicate different types of triangles. If you need these sorts of constants for your solution, use enumerations instead:

          enum StopLightStatus { STOP, YIELD, GO };
  

• Do not attempt to write your solution to handle "all" inputs. There is no requirement that your program gracefully handle invalid characters or other bad data; you can assume the user enters all three numbers, and that any numbers entered are floats.
• Do consider putting all of your triangle classification code in a single (.cpp) file with an associated .h file. A separate file for each function does not scale to real projects, and it makes grading your solutions much harder. You will have a separate file for tests.
• Do put all source code and build products in a single directory. make can be used for multi-directory projects, but it's not trivial to implement. Besides, this project is too small to make that effort valuable.
• DO follow the coding standard. In particular, ensure your IDE is configured to not insert tab characters and be sure your name is in all source files. If typing four spaces bothers you (it probably should!), switch to the two-space indent that is becoming standard at many organizations. You quickly learn to read those indents. Also, be sure to name constants in your code such as the epsilon to determine if two numbers are nearly the same or values used to classify an isosceles triangle.
• Do not declare named constants for test values used in your test code. Naming these values is an anti-pattern in testing unless there is a very clear reason for the name. Named constants in test code mean that everyone has to look up the value to verify the test; it is much faster and less error-prone to just read the test. For tests, it is more important that data be local than modifiable. If you do have common setups, use the test library features to ensure particular test objects are available for each test. An exception to this would be a constant that is specified in the requirements such as the 1e-4 above - it might be very useful to have this value available to tests so you can write tests like

          EXPECT_TRUE(abs(90.0 - largest_angle) <= TOLERANCE);
  

  or

          EXPECT_TRUE(abs(90.0 - largest_angle) > TOLERANCE);
  

  You can also use the tolerance to create triangles that are just barely not right triangles:

          double a = 45.0, b = 90 + 2*TOLERANCE, c = 180.0 - b - a;
  

  This triangle would be at the boundary between obtuse and right triangles.
• Do ensure your tests consider boundary cases and odd cases like greater than 360 degrees in a set of angles.
• Avoid table-driven tests unless they are critical to a project. Large numbers of tests are far less value than a few tests that are focused on potential trouble spots.
• Do use easy-to-compute values for basic testing. It should be easy for the reader to confirm the expected output is correct. You may wish to add tests for more complex values that cannot be computed by hand, but these should be in addition to the simpler cases.
• Do break your tests into small chunks using the standard model of setting up data, calling the code under test, and validating the results. The single-assertion-in-each test does not scale because it typically means duplicating a lot of code to write tests that use the same setup. Conversely, it is often natural to check closely related conditions in the same test. However, if the test is difficult to follow, break it up. Writing tests that people cannot understand is useless.
• Do name your test procedures in a way that the goal of each test is clear from the name. With good names, there is no need to document procedures with comments.

Submission

Create a Makefile that builds your system (including the test executable), then create a Dockerfile that does the build and test run. Note that your tests will likely not run your main, but are to perform thorough testing for all functionality other than input and output.

Capture an evidence document showing that

• All tests pass using the implementation you submit. Be sure this actually shows the tests passed - if necessary, modify a source file to force the tests to be re-run.
• Introducing a logic error in the code means that some tests fail. Be sure to document the logic error you introduced!

Ensure your error is not a syntax error; the question is not whether Docker shows your code fails to build - that is easy to see using a compiler - but whether Docker shows when the code runs but gives the wrong result. Be careful to keep your evidence document focused on useful sections of the Docker output; I do not need installation steps, but I do need to see that the tests run and produce the correct output. A critical part of the output is both the test runs and the summary at the end stating how many tests passed and how many failed.

Submit a .ZIP file containing your source code and appropriate build files in the topmost directory. Do not include non-source files (like screen captures, .git folders, etc.) or build projects (like .o files or executables). In particular, your .ZIP will not contain your report. In most cases, you will submit a .ZIP containing Dockerfile, Makefile, .h files, and .cpp files. A Readme.txt is always appropriate (capturing project goals, build steps, and testing), but not required for this assignment.

Avoid some common errors: tabs in source files, forgetting to put your name in files, submitting files I do not need, and failing to satisfy the coding standard. Double-check the writeup when you are done to make sure you have completed everything; issues like forgetting to test within a tolerance value result in 10-point deductions. This assignment is about learning to write good, automated tests, so logic of classifying triangles is just a small part of the points for this assignment. If you have any difficulty with that logic, talk to your instructor for lots of hints!