TDD-Deciphered.com

« Previous: Part 8: Putting the Rotors in place

Part 9: Implementing the real rotors

16/01/2010

We can now go on to populate the first five rotors that were provided with the German Military Enigma Machines, rotors I through V, as classes Enigma_Rotor_I to Enigma_Rotor_V.

That's a lot of very fragile data, of course, and we need a good way to check it. How can we do this?

There are two risks:
1) We get the data completely wrong; ie, we populate data for the wrong wheel.
This is reasonably unlikely, and we can visually check it quite easily.

2) We make a minor error in copying the rotor specification into our class; for example we miss an input/output pair, or get the wrong output for an input.
If we were to try and check this directly, we'd end up comparing the data we type in for the class with the data we type in for the tests - not ideal. But we can do some fairly smart heuristic tests:

i) For each wheel, each letter must appear as an input exactly once, and as an output exactly once.
ii) Each wheel must have exactly 26 I/O pairs.

These are easy to code, work for all current and future rotors, and are reasonably immune from human error.

We add this test code to RotorTest.php:

/**
     * Make sure each rotor's mapping is coherent
     * @return null
     * @dataProvider fiveRotorsDataProvider
     */
    function testCoherentRotorIdentities(Enigma_Rotor_Abstract $rotor)
    {
        $rotor=new Enigma_Rotor_I;
 
        $mapping=$rotor->getCoreMapping();
        $this->assertTrue(is_array($mapping));
        $this->assertSame(26,count($mapping));
 
        $inputsSeen=array();
        $outputsSeen=array();
 
        foreach($mapping as $i=>$o) {
            $this->assertFalse(isset($inputsSeen[$i]),'Input seen before');
            $this->assertFalse(isset($outputsSeen[$o]),'Ouput seen before');
            $this->assertSame(
                1,
                preg_match('/^[A-Z]$/',$i),
                'Input "'.$i.'" must be upper-case letter'
            );
            $this->assertSame(
                1,
                preg_match('/^[A-Z]$/',$o),
                'Output must be upper-case letter'
            );
            $inputsSeen[$i]=true;
            $outputsSeen[$o]=true;
        }
 
        $this->assertSame(26,count($inputsSeen));
        $this->assertSame(26,count($outputsSeen));
 
    }
 
    function fiveRotorsDataProvider()
    {
        return(array(
        array(new Enigma_Rotor_I),
        array(new Enigma_Rotor_II),
        array(new Enigma_Rotor_III),
        array(new Enigma_Rotor_IV),
        array(new Enigma_Rotor_V),
        ));
    }

And, if we've built our rotors correctly, we get clean passes.

So, we've now built a full set of rotors. Now, we can get back to the task of testing their rollover behaviour in the required array of slots.

To recap, we first want to ensure that, if the rotor in slot 1 is in its pre-turnover position, incrementing its position should cause slot 2 to turn its rotor too.

The main problem at this point, however, is that we've not yet implemented the idea of a turnover position. These positions, for the five rotors we've built so far, follow the mnemonic coined at Bletchley Park: "Royal Flags Wave Kings Above". (These are the post-turnover positions).

There are a few ways we could implement this, but we'll take our clue from the mechanical properties of the system; pegs at a given position on the wheel, which, when the wheel is in the appropriate position, cause a "knock-on". Most wheels have one peg; some have two, and the pegs were movable in some (experimental?) models.

It's the position of the peg in the slot that counts, so we'll get the slot to check the wheel, and have the slot trigger a turnover when a rotor has a peg at the current position.

So, rotor 1 needs to respond to hasPegAtPosition($position) with a Boolean answer. Since all rotors have this behaviour, we put it in the Enigma_Rotor_Abstract class, and, as with the core mapping, store the position as a private property. (For our test rotors, Enigma_Rotor_Configurable, we'll assume a default position of "A" for now, until we need to do something smarter).

So, Enigma_Rotor_Abstract gains:

protected $_pegPositions=array();
 
/**
     * Do we go "tick" here?
     * @return bool
     */
 public function hasPegAtPosition($position) {
    return(in_array($position,$this->_pegPositions));
} 
 
and Enigma_Rotor_I gains
 
protected $_pegPositions = array(‘R');
 
and so on for the other rotors. 
 
We can test these wheels in RotorTest with:

We can similarly give the slots the ability to check for turnover, with a knockOnDue() function in Enigma_Rotor_Slot. To test this, we'll need to load a slot with a known rotor in a known position.

(Note: We treat KnockOn as the cause, and Turnover as the effect)

In RotorSlotTest.php, we put very similar tests to the above:

/**
     * Check that slots know when to trigger a "Knock-On"
     *
     * @dataProvider fiveRotorsTurnoverDataProvider
     * @param $rotor Enigma_Rotor_Abstract
     * @param $offsetTurnoverDue
     * @param $offsetNoTurnover
     * @return null
     */
    function testSlotKnockOnDue(Enigma_Rotor_Abstract $rotor,
        $offsetTurnoverDue,$offsetNoTurnover)
    {
        $slot=new Enigma_RotorSlot();
        $slot->loadRotor($rotor);
 
        $slot->setRotorOffset($offsetTurnoverDue);
        $this->assertTrue($slot->turnoverDue());
 
        $slot->setRotorOffset ($offsetNoTurnover);
        $this->assertFalse($slot->turnoverDue());
    }
 
 
    function fiveRotorsTurnoverDataProvider()
    {
        return(array(
        array(new Enigma_Rotor_I,'R','Z'),
        array(new Enigma_Rotor_II,'F','X'),
        array(new Enigma_Rotor_III,'W','P'),
        array(new Enigma_Rotor_IV,'K','N'),
        array(new Enigma_Rotor_V,'A','F'),
        ));
    }

and allow ourselves to pass them by adding:

public function turnoverDue()
    {
        return($this->_rotor->hasPegAtPosition($this->getRotorOffsetAsCharacter()));
    }
 
    public function getRotorOffsetAsCharacter ()
    {
        return $this->_alphabetPositionToCharacter($this->getRotorOffset());
    }

to the Enigma_RotorSlot class.

We then need to link the rotor and slots, and the electrical and mechanical stages together. Remembering that the mechanical phase happens first:

Increment slot 1's rotor position.
Is this slot's rotor now in the knock-on position?
If so:
Cause slot 2's rotor position to increment.
Is slot 2's rotor in the knock-on position... etc

Note that slot2 can only cause a knock-on in slot3 if it itself is being moved on - so it makes sense to put this check-and-trigger in the Enigma_RotorSlot::incrementRotorOffset() function.

We'll implement this simply in the Enigma_RotorSlot class as follows:

public function incrementRotorOffset()
    {
        $this->_rotorOffset++;
        if($this->_rotorOffset>26) {
            $this->_rotorOffset=1;
        }
 
        //If we're in turnover position, notify the next slot
        if($this->turnoverDue()) {
            $this->notifyTurnoverObserver();
        }
    }
 
        public function registerTurnoverObserver(Enigma_RotorSlot $observer)
    {
        $this->_turnoverObserver=$observer;
    }
 
    public function notifyTurnoverObserver()
    {
        if($this->_turnoverObserver) {
            $this->_turnoverObserver->incrementRotorOffset();
        }
    }

How do we test this though? If it works correctly, it'll cause a turnover in the next rotor up, but we'll have to set and then read this rotor's position – we're testing an indirect effect, which is slightly risky.

However, as this is the best we know for now, let's give it a try.

function testNextRotorKnockOnSimple()
    {
        //Three slots, as per a basic enigma device
        $rotorSlots=array(new Enigma_RotorSlot, new Enigma_RotorSlot, new Enigma_RotorSlot);
 
        //each slot is observed by next one up
        $rotorSlots[1]->registerTurnoverObserver($rotorSlots[2]);
        $rotorSlots[0]->registerTurnoverObserver($rotorSlots[1]);
 
        //load the slots
        $rotorSlots[0]->loadRotor(new Enigma_Rotor_I);
        $rotorSlots[1]->loadRotor(new Enigma_Rotor_II);
        $rotorSlots[2]->loadRotor(new Enigma_Rotor_III);
 
        //put slot 0's wheel slightly before its turnover position
        $rotorSlots[0]->setRotorOffset('P');
        //put other wheels in known position
        $rotorSlots[1]->setRotorOffset('A');
        $rotorSlots[2]->setRotorOffset('A');
 
        //Check 0 and 1 are in expected positions:
        $this->assertSame('P',$rotorSlots[0]->getRotorOffsetAsCharacter());
        $this->assertSame('A',$rotorSlots[1]->getRotorOffsetAsCharacter());
        $this->assertSame('A',$rotorSlots[2]->getRotorOffsetAsCharacter());
 
        //Turn over slot 0
        $rotorSlots[0]->incrementRotorOffset();
        //0 moves, 1 stays still
        $this->assertSame('Q',$rotorSlots[0]->getRotorOffsetAsCharacter());
        $this->assertSame('A',$rotorSlots[1]->getRotorOffsetAsCharacter());
        $this->assertSame('A',$rotorSlots[2]->getRotorOffsetAsCharacter());
 
        //Turn over slot 0
        $rotorSlots[0]->incrementRotorOffset();
        //Bottom 2 move this time
        $this->assertSame('R',$rotorSlots[0]->getRotorOffsetAsCharacter());
        $this->assertSame('B',$rotorSlots[1]->getRotorOffsetAsCharacter());
        $this->assertSame('A',$rotorSlots[2]->getRotorOffsetAsCharacter());
    }

That looks promising (and works!), but how could we ask "has slot[1]'s rotor had incrementRotorOffset called once?"

One option would be to add code to the Enigma_RotorSlot class to count the number of times incrementRotorOffset class was called, and then check that afterwards – but this would bulk out the class with test-only code and impair its functionality. We should be able to test the class without modifying it.

What if we had a piece of test kit we could drop in slot[1] which we told "Expect one call to incrementRotorOffset"? Well, if we could tell it what we meant by "expect" (or when to stop expecting) that might work, but again the code could be complex if we have to build it by hand. Plus, our registerTurnoverObserver() function demands that its argument is an Enigma_RotorSlot, so we'd have to extend that class.

However, PHPUnit provides exactly that functionality internally, for any class. It's called "Mocking", and we use to create a "Mock Object" that replicates the slot's functionality. Instead of the mass of hand-built code, we implement it as follows:

$mockRotor=$this->getMock('Enigma_RotorSlot', array('incrementRotorOffset','setRotorOffset'));
 
$mockRotor->expects($this->once())->method('incrementRotorOffset');

Our first line says "Create a fake Enigma_RotorSlot with incrementRotorOffsets() and setRotorOffset() functions". The second says "This class' incrementRotorOffset() function must be called once in the current test function".

Those are about the only changes we need to make to our test function:

function testNextRotorKnockOnMock()
    {
        $mockRotor=$this->getMock(
            'Enigma_RotorSlot', 
            array('incrementRotorOffset','setRotorOffset')
        );
 
        $mockRotor->expects($this->once())->method('incrementRotorOffset');
 
        $rotorSlots=array(new Enigma_RotorSlot, $mockRotor, new Enigma_RotorSlot);
 
        //each slot is observed by next one up
        $rotorSlots[1]->registerTurnoverObserver($rotorSlots[2]);
        $rotorSlots[0]->registerTurnoverObserver($rotorSlots[1]);
 
        //load the slots
        $rotorSlots[0]->loadRotor(new Enigma_Rotor_I);
        $rotorSlots[1]->loadRotor(new Enigma_Rotor_II);
        $rotorSlots[2]->loadRotor(new Enigma_Rotor_III);
 
        //put slot 0's wheel slightly before its turnover position
        $rotorSlots[0]->setRotorOffset('P');
        //put other wheels in known position
        $rotorSlots[1]->setRotorOffset('A');
        $rotorSlots[2]->setRotorOffset('A');
 
        //Turn over slot 0
        $rotorSlots[0]->incrementRotorOffset();
        $rotorSlots[0]->incrementRotorOffset();
    }

This is a simple application of this capability (and one we could have been able to work around), but shows how it can be used. However, it works, and with that we've tested all the mechanical functionality of the Enigma system.

Next time, we'll finish up the electical parts of the system, and look at how to assemble the components into a working machine.

« Previous: Part 8: Putting the Rotors in place

Index

Next: Part 10: Assembling the Machine »

TDD-Deciphered.com

Part 9: Implementing the real rotors

Navigation

Contact