A. Introduction

Today you will get started on testing Project 2: Qirkat. If you have not already, take a look at the specs here. Feel free to use the tests that you write in this lab as part of the tests you submit for your project.

B. Lab

In this lab, we will go over how to test your project. There are two components to testing: unit testing and integration testing. Unit tests make sure that a function or subset of functions work properly when given a specific input. Integration tests ensure that the entire project works properly as a whole. Both are important because while individual functions may work properly in an isolated environment, once they start taking in values from other parts of the program, they could break. Here's a visual demonstration of why we need integration tests.

Unit Testing

You will be writing unit tests in the same way you did in project 1. If you decide to create a new file outside of MoveTest.java, BoardTest.java, and CommandTest.java, make sure to link it in UnitTest.java.

Your first task for this lab will be to write some unit tests (on top of what is already provided) for the Board class! Look in MoreBoardTests.java. We have provided a series of functions that enables you to set the initial board state to anything you want, provided in the form of a 2D character array. This might prove helpful, since we have also provided a function, resetToInitialState, that can let you reset any board to the initial board state anywhere within your test cases. However, it relies on your Board#setPieces function being correct.

Note that in order for the code in MoreBoardTests.java to compile, you will have to copy it over into your Qirkat directory and write the tests there. When submitting this lab, make sure to copy the contents of the file back into the file in this lab!

While getting tests to pass actually requires that you completely implement the functions being tested, you don't have to pass them right now. Instead, you should take the time to create scenarios where you know what is expected to happen. As you fill out the methods, don't forget to run these tests to make sure that your function is correct.

If you need help coming up with how to create Moves to input to your functions, take a look at BoardTest.java.

This is a common paradigm known as Test-Driven Development(TDD). It's very helpful because it forces you to actually know the expected behavior of the function for a certain input; knowing this will give you an idea of what and how you should implement it.

Integration Testing

Everything we discuss in this section can be found in testing/README in the qirkat testing project directory. Make sure to read the file as this lab will only discuss a subset of all the testing functions that may be important to your project.

As with all projects, you will need to write tests to ensure your code is correct. For Qirkat, you will need to provide both unit tests and integration tests.

Integration tests are stored in the testing folder and are run using the test-qirkat.py script. Make sure you are using Python 3 (run python3 test-qirkat.py). The script takes in, as an argument, a text file defining the integration test case. Text files contain lines that either insert commands into the command line and Qirkat program, or defines lines to be expected as output.

Take a look at testing/test01.inp included here for convenience:

# Trivial test of initial board.
java -ea qirkat.Main
dump
@<===
@<  b b b b b
@<  b b b b b
@<  b b - w w
@<  w w w w w
@<  w w w w w
@<===
quit

Let's step through this line by line.

• Line one is a comment. All lines beginning with a pound # or are empty are ignored by the testing script.
• The next line runs java -ea qirkat.Main to start an instance of the Qirkat program from command line.
• The proceeding line is fed in as input to the Qirkat program. Here we are testing if dump was correctly implemented.
• If dump is correctly implemented then it should print out the following 9 lines. Any line @<TEXT denotes expected output from the Qirkat program. Note that expected output is white space sensitive! If you're confused about why your integration test may be failing, make sure to check your test cases for any extraneous white spaces that mess up the expected output's formatting.
• Finally, the Qirkat program is closed using quit.

This is a very basic integration test. The script has the power to run more complicated tests that you will find useful as you progress through the project.

Understanding questions

Find someone to discuss these questions with. Once you and your partner have reached a conclusion, flag a TA/tutor/lab assistant and explain to them the solutions for each question.

1. How do you start a game of Qirkat between two human players?
2. What might be a good data structure to keep track of the state of the board and which direction a piece can move?
3. What is the difference between determining if a jump is legal and if a player can execute a jump (or potentially a series of jumps), and where is this difference reflected in the code?
4. What does it mean to linearize the board and why might this be helpful?

When coding your AI, it will be informative to provide a test case that plays a Qirkat game between two program instances. Here are some questions that might help you test your AI. If you are stuck, take a look at testing/README.

1. How do we create a test case that plays a game between two Qirkat instances?
2. What is the purpose of the lines @send black...ENDPATN and @recv black...ENDPATN?

Task

Your task for this lab will be to write and submit two integration tests. Test case 1 should do the following.

• Start the Qirkat program and set the playing board to be formatted as below, starting on white's turn. Take a look at the rest of the tests in your proj2 testing folder if you get stuck.

b - - - w
- b - w -
- - b - -
- w - b -
w - - - b

• Dump the board. What should your result look like? Write the expected result using @
• Perform the move b2-c2. What should happen?
• Afterwards, make the move d2-b2. What should happen?
• Make the move a1-a2. What should the board look like?
• Make the move a5-b5. Dump out the board.
• Make the move a2-c2-c4-a4 and dump the board. What should the board look like?
• Quit the game.

Write this test case and place it into the text file test-qirkat-1.inp. The second integration test will be up to your design. Write a case that tests for either an interesting edge case or a specific functionality in the program. Maybe you could check to see if you print out error messages correctly, or ensuring that all (or a subset of) the rules of Qirkat are enforced. It will be in your best interest to test something that the given tests don't already test. Store this case in test-qirkat-2.inp. Finally, submit these two text files. Note that even though you wrote these in lab, they can still be used in your final project submission (hooray for getting started early)!

Running the staff qirkat

When writing tests, it might not always be clear what the correct output should be. This is why we have given you access to the staff solutions for Qirkat. You may access the staff solution by the following steps:

• SSH into your instructional account ssh -X cs61b-xxx@ashby.cs.berkeley.edu.
• Run staff-qirkat.
• Run staff-qirkat --display for the Qirkat GUI.

However, PLEASE understand that the behavior of staff-qirkat is NOT the definition of the project, and you should always follow the spec.

A quick note on running the GUI for staff-qirkat. Since you are running the GUI remotely, you will need to have X forwarding setup before hand. Macs can install XQuartz to handle this while Windows machines will need to do something a bit trickier. Alternatively, you can physically log into a lab computer and run staff-qirkat.

C. Deliverables

Please tag and submit MoreBoardTests.java, test-qirkat-1.inp and test-qirkat-2.inp.