Setting up

Prerequisites

  • JDK 11

  • IntelliJ IDE

Importing the project into IntelliJ

  1. Fork this repo, and clone the fork to your computer

  2. Open IntelliJ (if you are not in the welcome screen, click File > Close Project to close the existing project dialog first)

  3. Set up the correct JDK version

    1. Click Configure > Project Defaults > Project Structure

    2. If JDK 11 is listed in the drop down, select it. If it is not, click New…​ and select the directory where you installed JDK 11

    3. Click OK

  4. Click Import Project

  5. Locate the project directory and click OK

  6. Select Create project from existing sources and click Next

  7. Rename the project if you want. Click Next

  8. Ensure that your \src and \test\java folders are checked. Keep clicking Next

  9. Click Finish

  10. Add JUnit 5 to classpath

    1. Open any test file in \test\java and place your cursor over any @Test highlighted in red

    2. Press ALT+ENTER and select Add 'JUnit5.3' to classpath (if 5.3 is not available, any 5.x will suffice)

      AltEnterSelectJunit53

    3. Select org.junit.jupiter:junit-jupiter-api:5.40 from the dropdown and click OK (if 5.40 is not available, choose any 5.4x that is later than 5.40)

      SelectJUnitVersion

  11. Run all the tests (right-click the test folder, and click Run 'All Tests')

  12. Observe how some tests fail. That is because they try to access the test data from the wrong directory (the working directory is expected to be the root directory, but IntelliJ runs the test with test\ as the working directory by default). To fix this issue:

    1. Go to Run → Edit Configurations…​

    2. On the list at the left, expand JUnit, and remove all the test configurations (e.g. All in test) by selecting it and clicking on the '-' icon at the top of the list

    3. Expand Templates (or Defaults if you are using an older version of IntelliJ before 2018.2), and ensure that JUnit is selected

    4. Under Configuration, change the Working directory to the addressbook-level2 folder

    5. Click OK

  13. Run the tests again to ensure they all pass now

Design

mainClassDiagram

Testing

I/O tests

Windows

  1. Open a DOS window in the test folder

  2. Run the runtests.bat script

  3. If the script reports that there is no difference between ACTUAL.TXT and EXPECTED.TXT, the test has passed

Mac/Unix/Linux

  1. Open a terminal window in the test folder

  2. Run the runtests.sh script

  3. If the script reports that there is no difference between ACTUAL.TXT and EXPECTED.TXT, the test has passed

JUnit tests

  • In IntelliJ, right-click on the test folder and choose Run 'All Tests'

Troubleshooting test failures

  • Problem: How do I examine the exact differences between ACTUAL.TXT and EXPECTED.TXT?
    Solution: You can use a diff/merge tool with a GUI e.g. WinMerge (on Windows).

  • Problem: The two files look exactly the same, but the test script reports they are different.
    Solution: This can happen because the line endings used by Windows is different from Unix-based OSes. Convert the ACTUAL.TXT to the format used by your OS using some utility.

  • Problem: Test fails during the very first time.
    Solution: The output of the very first test run could be slightly different because the program creates a new storage file. Tests should pass from the 2nd run onwards.