CS21 Lab 7: Mastermind

Due before 11:59pm Tuesday night Oct. 25

Please read through the *entire* lab before starting. Run update21 to create your cs21/labs/07 directory and create your programs for lab 7 in this directory.


Over the next two weeks you will write a program that plays the game Mastermind. For lab 7, you will focus on using top-down design to create the overall structure of the program. Once your proposed structure has been reviewed by your professor, you will use bottom-up implementation and unit testing to incrementally implement and test the full program as lab 8.

The wikipedia page about Mastermind describes the game and also some ineteresting results obtained by computer scientists who have studied the game. If you take more computer science courses at Swarthmore, you will learn about NP-complete problems in our Algorithms and Theory courses. Also, you can try playing the game on-line here

We will implement a slightly modified version of the Mastermind game:


Mastermind is a code-breaking game for two players. For our version, the computer will be the code maker and the program user will be the code guesser or breaker.

At the start of the game the computer will create a 4-letter code, where each letter is one of 6 possible letters (abcdef). To simplify the game, our version will not allow a letter to be used in the code more than once. Possible codes are abcd, eafb, cbaf, and so on. The user then has 10 chances to guess the code. After each guess the computer tells the user how many exact and partial matches they achieved.

To make things more concrete let's consider some examples. Below is an example of just part of the game -- a code (usually not shown!) and multiple guesses, to show exact and partial matches.

code = "eadb"

Enter guess number 1: abcd
             0 exact matches (letter *and* position correct)
             3 partial matches (letter correct, position incorrect)
Enter guess number 2: efab
             2 exact matches (letter *and* position correct)
             1 partial match (letter correct, position incorrect)
Enter guess number 3: cdef
             0 exact matches (letter *and* position correct)
             2 partial matches (letter correct, position incorrect)
Enter guess number 4: cabe
             1 exact match (letter *and* position correct)
             2 partial matches (letter correct, position incorrect)
General Requirement for lab 8 (a fully working program)
In the lab 8 assignment we will give you more details about specific requirements for the mastermind program, but here we list the general requirements for your solution to help you solve the Top-Down-Design part for lab 7.

The main requirements for a working program:

  1. The program prints out a welcome message and the game rules for the player
  2. The computer generates a secret code to guess
  3. The user enters up to 10 guesses, after each guess the program prints out the number of exact and partial matches
  4. The program prints out a win or lost message to the player, and if the player loses, it should print out the secret code.
  5. Your program needs to ensure that only valid input values are entered by the user (we will explain this more in lab 8)
Also, to help with your Top-Down-Design for lab 7, here is an example run of a completed mastermind program (a lab 8 solution.)

Requirements for lab 7
For this lab you will turn in your top-down design (TDD) before fully implementing any of the functions.

You should create a file mastermindTDD.py containing your design and email it to your professor (the email directions are in the Submit section below.) We will then look over your design, make comments on it, and send it back. If we think your design is inadequate we will ask you to fix and resubmit it. Once we have approved your top-down design, you can implement the full program, which will be described in more detail in lab 8.

Here are the top-down design requirements:

Here is an Example TDD stubbed out program that includes the main control flow of the program. Your TDD solution should be similarly structured.

Special Submission for lab 7: once you have your TDD solution, with all functions stubbed out and the main flow implemented with calls to your stubbed out functions, you will send us your solution via email.

Send us your program using email like this:

         $ cd cs21/labs/07
         $ mail newhall < mastermindTDD.py 

Once you email us your design, we will try to get comments back to you within 24-36 hours. However, if everyone emails us their design at the same time, it may take longer. You are encouraged to start your design early, so you have enough time to get our helpful comments and still implement the full program.