Assignment 1: Testing Against Specifications

Due dates:

• Examplar: Monday, Sep 16 at 8:59pm

• Self-evaluation: Tuesday, Sep 17 at 11:59pm

Starter files: code.zip

1 Purpose

The primary goal of this assignment is to have you practice testing and understand the level of testing this class requires on a small set of interfaces. The secondary goal is to have you understand how good documentation can help you test and understand the behavior of code when there is no implementation.

2 Getting started

Before you start this assignment, please ensure that you have all the necessary tools to complete an assignment. They include:

• Java 11 SDK

• IntelliJ IDEA

• Successful registration on the Handins server to submit an assignment

• Successful registration on Piazza to post and get answers to common questions

Please review the directions on the course page if you need help setting up any of this, or talk to the course staff.

3 Your task: Writing Examples to Catch Chaffs

In this assignment, you will be writing examples to catch all of the chaffs the instructor has created. These chaffs were implemented to fail according to the documentation of the code. You must use the Javadocs in the code alongside the explanations in the specification below to write your examples and find those chaffs.

4 Overview: Representing simple file systems

In this assignment, we’ll think about file systems and some possible data representations for them. For now, we will make the system read-only (i.e. cannot add or change files once the file system is created) and we will be using the Mac style file separator (i.e., we use the / as a file separator), and expect only three behaviors:

• Ask for the amount of space used by all files in the file system

• Ask for the capacity of a file system (how much it can hold)

• Search for a given word or phrase within the file system

The starter code contains three classes that are all parts of the file system:

• the ReadOnlyFileSystem: the class a client uses to interface with the system

• the SimpleDirectory: a file that contains other files in a particular file system

  To be specific, we are loosely mimicking the ext4 file system, which by default sets the size of a directory to 1 file block, which is 4Kb (or 4096 bytes) in size by default. You can read more about it here, but all of that information is not required for this assignment. Take an operating systems course instead to learn more.

• the StringFile: a file that contains written content

The Javadoc in those classes should explain what they are intended to represent.

5 Pretty printing

The prettyPrint method produces a human-friendly visual of the file system in a string for debugging purposes. An example of a pretty printed filesystem appears below.

+-root/
| +-data/
| | +-experiment/
| | | +-exp-name.log
| | | +-filesystem/
| | | | +-data.log
| +-lib/
| | +-cool-thing.txt

• All files in the file system must be preceded by a "+-" and then their name followed by a line-break "\n".

• Directories must have the "/" follow their name and all of their contents indented as shown above. In particular, each level of indentation adds a "|" and a space to the output of the next line. The indentation dictates how many directories inside a certain file is. For example, the root directory is at the very top. The filesystem directory is three directories deep, inside of root, then data, and finally experiment.

• Directories with no content are still printed. The only difference is nothing is indented below them.

6 Creating examples to guide implementations

With the system sufficiently explained, your task is to write a collection of test methods in the ExamplarFileSystem class (in the cs3500.hw1.filesystem package in your test folder) that demonstrate how these classes are supposed to work. These tests will function as examples of file systems.

However, you do not have a working implementation nor should you implement any of them. So your tests will depend on the given constructors and interfaces to create your examples.

Fixed a discrepancy due to an off-by-one error. Hints for the chaffs:

• Chaffs #00-05: These are related to the constructors for various classes. Take a look at the documentation carefully. What does the documentation guarantee? How can you check those guarantees?

• Chaffs #06-08: These are related to the contents method. Notice that there are two different signatures for this method! They do have different chaffs associated with them. Again, what guarantees does the documentation make?

• Chaffs #09-11: These are related to the prettyPrint method. Read the specification above very carefully to understand what is expected from that method.

• Chaffs #12-15: These are related to the search method. Notice that every version of search has the same behavior. Therefore, you only need to catch the chaff once for one class and you could develop the same tests for all.

  We modified Chaffs #13-16 in this way to remove redundancy in your examples and frustration. For a regular assignment, you would test all relevant classes as well because each class can hide its own buggy implementation.

• Chaffs #16-19: These are related to the totalSize method in SimpleDirectory. Consider what the documentation says about this method as well as the possible shapes of directories. You might write a test that catches two or more of these. Consider special cases or more general cases of those examples.

7 Grading standards

For this assignment, you will be graded on

• the metrics reported by Examplar,

• whether your code compiles,

• how well you follow the style guide.

• whether your program is suitably commented or examples have suitable names

7.1 The style guide

Coding style is important. For this class we follow Google’s Java style guide. It’s comprehensive but not very long, so I suggest reading the whole thing and then referring to it as needed.

While it can’t yet take on full responsibility for formatting code—much less for programming style more broadly—your IDE may be able to help you follow the code formatting portion of the style guide:

• For IntelliJ IDEA, download intellij-java-google-style.xml and save it in the config/codestyles/ subdirectory of your IntelliJ configuration folder. Then from within IntelliJ, go to File > Other Settings > Default Settings..., then in the dialog that pops up, go to Editor / Code Style, and select it in the Scheme dropdown, where it should have appeared as an option. If you’ve already created a project, then you’ll additionally need to set this as the project style, using File > Settings.

• Check here for more info.

8 Submission

Ready to submit? Look at the Design Principles Master List first! (Not all items there may apply to this assignment)

8.1 Deliverables

• For your implementation: either submit only ExamplarFileSystem.java OR submit a zip file containing

  • an empty src folder or a src folder with a single empty file called ignored.txt

  • a test folder with the needed folders and ExamplarFileSystem.java

  In the zip file method, these folders should mimic the folder structure required for your packages. Please do not put these folders within another folder before submitting, as the grader will not find your files:

  A properly-formatted zip file:		An improperly-formatted zip file:
  my-submission.zip +-src/ | +-ignored.txt (an empty file) +-test/ | +-cs3500/ | | +-hw1/ | | | +-filesystem/ | | | | +-ExamplarFileSystem.java		my-submission.zip +-My Awesome Homework 1/ +-src/ | +-cs3500/ | +-hw1/ | +-filesystem/ | +-Java files for filesystems +-test/ | +-cs3500/ | | +-hw1/ | | | +-filesystem/ | | | | +-ExamplarFileSystem.java

8.2 Instructions

You will submit the assignment on the Handins server. Follow these instructions:

1. Log in to the server using the link above, using your Khoury account (not your Northeastern account). Follow directions on the course page if you do not have a Khoury account or have forgotten your password.

2. You must be registered as a student to CS 3500 for Fall 2023 on the handin server. Follow directions on the course page if you have not applied for registration.

3. Submit the zip file you made above to the relevant assignment (“Hw 1”) on the submission server. Note that for the autograded portions, it may take some time to see feedback. This time increases as we get closer to the deadline, because many more students tend to submit. Please be patient!

4. You have two submissions for this assignment: the implementation submission, and the self-eval. Make sure to submit to each of them by their respective deadlines.