Doctests are something that's fairly unique to Python.

Other languages have them, of course,

but they're not always as nicely integrated as they are with Python.

Remember how, when we define a function or class, we can write a docstring, or

a brief description of what the function or class does?

Well inside that docstring you can also write a test.

Let's go to Workspaces and check it out.

This script probably looks familiar to you.

It's a slightly modified and

improved version of our Dungeon game from the Python collection's course.

There are several functions in here, that should be pretty easy to test,

through doctests.

So, let's see about adding some of those.

This also gives us a really great opportunity to add

in explanatory docstrings to our functions and to the file itself.

So, we can skip this first function.

We don't need to test it,

because all this function does is use Python to call a system level command.

We know that the system-level thing is gonna work and

we know that the Python function is gonna work, or

rather, testing those two things is not our responsibility.

We can rest assure that they work because we know there are tests written for

them on the system and on Python itself.

So, we don't need to test it, but it doesn't hurt to go ahead and

add in a docstring.

So, we'll just say, you know, clear the screen.

Okay. And then another thing often really good

to do is to add a,

effectively a docstring to your entire app or to your entire script.

So, I'm going to add one up here that just says dungeon game, explore a dungeon

to find a hidden door and escape.

But be careful!

The gru is hiding somewhere inside.

And then I'm going

to add a created 2014 updated 2015.

Oops, not 2016, and author Kenneth Love.

You can of course put your own name in there, put whatever name you want.

You probably want to put, if you were doing this for a script yourself,

you probably want to put in, like, dates that you actually created these things.

But, I don't want to have to remember exactly when [LAUGH] it was that I wrote

which thing.

So, anyway.

Just a bit of housekeeping,

this just makes it a little bit nicer for somebody else who comes across this file.

Let's go add a test, though, to this next function, this build cells function,

and, see how to write a doctest.

So, we're actually gonna come down here, and we're gonna put in three quotes.

Just like we're writing a docstring,

doctests and docstrings are definitely heavily related.

And let's say what this function does.

So it's going to create and return a width

by height grid of two tuples or sometimes you'll see these called pairs.

So, now we need to write the test.

And I like to leave white space around my tests.

It helps for letting Python find the doctests.

Sometimes you'll get weird behavior if there's not this

blank line at the end of the test.

And this blank line leaves a bit of nice separation, so

you can see where the description ends and where the tests begin.

So, the way that we write our tests

is any statement that we want Python to run we start with three chevrons.

It looks like the Python shell.

So we want it to run cells equals build cells, a width of two and a height of two.

And then I want to do len cells, and a two by two grid should have four items in it.

So these are what we want to have happen, these two lines,

and this is what we're expecting back from Python.

So if we look at our function, we have this cells list.

And then for each row that's in our height and

then for each cell that's in our width,

we're going to append this pair of the two numbers.

And then in the end we're going to return our list.

So when we do this two-by-two, we should get back four items.

Okay.

Looks an awful lot like the Python shell, and we're actually going to, in a minute,

see how to build these things in the Python shell, but

first let's write one more.

Let's go down here to this get locations.

And, it's going to get cells.

So, once again, we're gonna say,

randomly pick starting locations for

the monster, the door, and the player.

Where am I at?

I'm at 82.

All right, we'll go back.

There we go.

Okay.

So how would we go about testing this?

Well, let's look at the function does.

We've actually seen this one before, but just let's go over it.

So we get a random place for the monster, a random place for

the door, random place for the player.

If the monster is equal to the door, or the monster is equal to the player, or

the door is equal to the player, then we wanna get brand new locations for them.

Finally, we send those back.

You may not have noticed, but

this is actually a really good example of a recursive function,

so some people are like, ooh, we need to learn about recursive, or recursion.

Hey, here it is.

Okay, so let's write this.

So, first of all we're gonna do, oops, I need my three chevrons,

cells equals build cells two by two.

We can use the other functions that are in the file, so we're call our cells file,

ou, our build cells function up there, and we're gonna say M, D and

P is equal to get locations for cells, and

then we're gonna make sure that M does not equal D, and D does not equal P.

That should come back as true.

And then we're going to do D in cells just to make sure it's in there.

And that should also come back as true.

Okay?

So let's save that.

Nothing too strange or weird in our test there.

We're just kind of using it like we normally would.

'Kay, let's look at our next function here, get_moves(player).

This is a little bit more complicated than these ones above.

We're doing a lotta checking in through here.

So, let's actually see about writing this one in the shell.

So let's add a couple of things in here first.

Let's describe it.

We're going to say based on the tuple of the player's position.

Return the list of acceptable moves.

[SOUND] Okay, so right here is where we would start to write our stuff.

But I don't want to write it here, I want to write it down here.

Okay.

So let's go into Python.

Oop, sorry, you know what, let's get out of here.

Let's go into our dungeon directory.

And now go into Python.

Okay, from dd game import Get Moves, cause that's something that we need to have.

And then if we look at Get Moves.

We see it's using this game dimensions constant.

And if we look at the top of the file.

Where game dimensions is designed, it's this tuple of five-five.

Let's let's define that our self so that we don't have to use the five-five one.

So we'll say game dimensions is, let's do two-two, let's stick to our small grid.

And then let's say get moves and

we'll pretend that our player is down in the corner.

And we'll say zero is, is over in the corner and we'll say zero, two.

So we run that and we get right up and down.

Okay. So that's pretty simple.

So what I'm going to actually do.

I don't need this from dd game, import get moves line.

That's a given from my test.

But I do need this GAME_DIMENSIONS = (2, 2), get_moves, and that RIGHT, UP, DOWN.

So I've got that, I'm gonna copy it, I'm gonna come,

let okay, let's exit out of here.

And then let's drop this down.

There we go.

Okay. I'm gonna come up here.

And I'm gonna paste my stuff in and I'm gonna tab it in, and I'm gonna save.

Hey look, there's my test.

I wrote the whole test.

Isn't that amazing?

I didn't even have to, like, I didn't have to write it.

I just did it in the, I mean okay, I wrote it in the shell.

But still, I didn't have to, come up with what the answers were.

I could let the function just run and see what happened.

Okay. So we've got a few tests.

Let's see about running these.

Let's see what happens.

There's a way that we could run the test directly from this file so

that when you run the file, it runs the test.

But I'm not a really big fan of that approach.

The main reason is because I don't always want doctest to run.

In fact, I usually don't want doc test to run.

I will list how to do that in the teacher's notes though.

So instead, let's actually just run it explicitly down here in our shell.

So, what we can do is we do Python dash M doctest, and then we do DD game.py.

So what is this Dash M.

So the dash M tells Python to load the doctest module.

And the doctest module has some special code written in it

that says you're going to give me a file and when you give me that file,

I'm going to look through that file for doctests.

And I'm going to find the doctests and I'm going to run them.

So, that's what we've done.

We've said, load the doctest module and then give it the dd_game.py file.

Nothing comes back.

Guess what?

That's a good thing.

Nothing comes back.

That means everything passed.

That's exactly what we want but, let's make on fail real quick.

Let's go right here to this one.

We know that right, up, and down are gonna come out.

So to make it fail let's get rid of up.

Okay, let's say up is not gonna come up.

We're just gonna get right and down.

Okay?

So we come down here and we run our test again.

And here's our fail, so our fail is actually really, really good.

I'm gonna run this one more time so we can see the whole thing.

Here we go.

So, this file failed on line 64.

So, really, we failed on line 65, but,

line 64 is the one that we ran and it didn't give us what we expected.

So, the failure, 65 has the wrong content.

64 is the line that gave us the wrong content, so

64 is where the failure happened.

So, we ran this.

We expected this, right?

But we got this.

So, to fix this test, we need to come back in here and add in up.

If we save and we run it again,

now, there's no output because all the tests are good.

I'm not going to write anymore doctests for this function, or for

these functions in this script.

If you want more practice, then I suggest you do it.

Go in and write doctests for all the rest of them.

You should be able to do it no problem.

Wow, doctests are really simple to implement, and run.

We should definitely write these when we're planning our code.

It's a lot simpler to write a doctest than a full test suite, especially for

simple sanity checks.

Or, to write tests before you start coding.

Doctests do have some serious shortcomings though.

They're pretty tightly bound to the code they're written on, so

you can't just reuse them for new functions or classes, and

all of their checking is done through string comparison, so

sometimes floats can be tricky or even impossible to test with doctests.

Since doctest won't solve all of our problems,

let's look at a more powerful solution, the unittest module.