~ubuntuone-pqm-team/python-mock/stable : revision 1

1

2

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"

3

"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

4

5

6

7

<head>

8

9

10

<title>Getting Started with Mock — Mock 1.0.1 documentation</title>

11

12

13

14

15

16

var DOCUMENTATION_OPTIONS = {

17

URL_ROOT: '',

18

VERSION: '1.0.1',

19

COLLAPSE_INDEX: false,

20

FILE_SUFFIX: '.html',

21

HAS_SOURCE: true

22

};

23

</script>

24

25

26

27

28

29

30

</head>

31

<body>

32

33

<h3>Navigation</h3>

34

<ul>

35

36

<a href="genindex.html" title="General Index"

37

accesskey="I">index</a></li>

38

39

<a href="examples.html" title="Further Examples"

40

accesskey="N">next</a> |</li>

41

42

<a href="magicmock.html" title="Mocking Magic Methods"

43

accesskey="P">previous</a> |</li>

44

<li><a href="index.html">Mock 1.0.1 documentation</a> »</li>

45

</ul>

46

</div>

47

48

49

50

51

52

53

54

<h1>Getting Started with Mock<a class="headerlink" href="#getting-started-with-mock" title="Permalink to this headline">¶</a></h1>

55

56

<h2>Using Mock<a class="headerlink" href="#using-mock" title="Permalink to this headline">¶</a></h2>

57

58

<h3>Mock Patching Methods<a class="headerlink" href="#mock-patching-methods" title="Permalink to this headline">¶</a></h3>

59

Common uses for <tt class="xref py py-class docutils literal">Mock</tt> objects include:

60

61

<li>Patching methods</li>

62

<li>Recording method calls on objects</li>

63

</ul>

64

You might want to replace a method on an object to check that

65

it is called with the correct arguments by another part of the system:

66

<div class="highlight-python"><div class="highlight"><pre>>>> real = SomeClass()

67

>>> real.method = MagicMock(name='method')

68

>>> real.method(3, 4, 5, key='value')

69

70

</pre></div>

71

</div>

72

Once our mock has been used (<cite>real.method</cite> in this example) it has methods

73

and attributes that allow you to make assertions about how it has been used.

74

75

Note

76

In most of these examples the <tt class="xref py py-class docutils literal">Mock</tt> and <tt class="xref py py-class docutils literal">MagicMock</tt> classes

77

are interchangeable. As the <cite>MagicMock</cite> is the more capable class it makes

78

a sensible one to use by default.

79

</div>

80

Once the mock has been called its <tt class="xref py py-attr docutils literal">called</tt> attribute is set to

81

<cite>True</cite>. More importantly we can use the <tt class="xref py py-meth docutils literal">assert_called_with()</tt> or

82

<tt class="xref py py-meth docutils literal">assert_called_once_with()</tt> method to check that it was called with

83

the correct arguments.

84

This example tests that calling <cite>ProductionClass().method</cite> results in a call to

85

the <cite>something</cite> method:

86

<div class="highlight-python"><div class="highlight"><pre>>>> from mock import MagicMock

87

>>> class ProductionClass(object):

88

... def method(self):

89

... self.something(1, 2, 3)

90

... def something(self, a, b, c):

91

... pass

92

...

93

>>> real = ProductionClass()

94

>>> real.something = MagicMock()

95

>>> real.method()

96

>>> real.something.assert_called_once_with(1, 2, 3)

97

</pre></div>

98

</div>

99

</div>

100

101

<h3>Mock for Method Calls on an Object<a class="headerlink" href="#mock-for-method-calls-on-an-object" title="Permalink to this headline">¶</a></h3>

102

In the last example we patched a method directly on an object to check that it

103

was called correctly. Another common use case is to pass an object into a

104

method (or some part of the system under test) and then check that it is used

105

in the correct way.

106

The simple <cite>ProductionClass</cite> below has a <cite>closer</cite> method. If it is called with

107

an object then it calls <cite>close</cite> on it.

108

<div class="highlight-python"><div class="highlight"><pre>>>> class ProductionClass(object):

109

... def closer(self, something):

110

... something.close()

111

...

112

</pre></div>

113

</div>

114

So to test it we need to pass in an object with a <cite>close</cite> method and check

115

that it was called correctly.

116

<div class="highlight-python"><div class="highlight"><pre>>>> real = ProductionClass()

117

>>> mock = Mock()

118

>>> real.closer(mock)

119

>>> mock.close.assert_called_with()

120

</pre></div>

121

</div>

122

We don’t have to do any work to provide the ‘close’ method on our mock.

123

Accessing close creates it. So, if ‘close’ hasn’t already been called then

124

accessing it in the test will create it, but <tt class="xref py py-meth docutils literal">assert_called_with()</tt>

125

will raise a failure exception.

126

</div>

127

128

<h3>Mocking Classes<a class="headerlink" href="#mocking-classes" title="Permalink to this headline">¶</a></h3>

129

A common use case is to mock out classes instantiated by your code under test.

130

When you patch a class, then that class is replaced with a mock. Instances

131

are created by calling the class. This means you access the “mock instance”

132

by looking at the return value of the mocked class.

133

In the example below we have a function <cite>some_function</cite> that instantiates <cite>Foo</cite>

134

and calls a method on it. The call to <cite>patch</cite> replaces the class <cite>Foo</cite> with a

135

mock. The <cite>Foo</cite> instance is the result of calling the mock, so it is configured

136

by modifying the mock <tt class="xref py py-attr docutils literal">return_value</tt>.

137

<div class="highlight-python"><div class="highlight"><pre>>>> def some_function():

138

... instance = module.Foo()

139

... return instance.method()

140

...

141

>>> with patch('module.Foo') as mock:

142

... instance = mock.return_value

143

... instance.method.return_value = 'the result'

144

... result = some_function()

145

... assert result == 'the result'

146

</pre></div>

147

</div>

148

</div>

149

150

<h3>Naming your mocks<a class="headerlink" href="#naming-your-mocks" title="Permalink to this headline">¶</a></h3>

151

It can be useful to give your mocks a name. The name is shown in the repr of

152

the mock and can be helpful when the mock appears in test failure messages. The

153

name is also propagated to attributes or methods of the mock:

154

<div class="highlight-python"><div class="highlight"><pre>>>> mock = MagicMock(name='foo')

155

>>> mock

156

157

>>> mock.method

158

159

</pre></div>

160

</div>

161

</div>

162

163

<h3>Tracking all Calls<a class="headerlink" href="#tracking-all-calls" title="Permalink to this headline">¶</a></h3>

164

Often you want to track more than a single call to a method. The

165

<tt class="xref py py-attr docutils literal">mock_calls</tt> attribute records all calls

166

to child attributes of the mock - and also to their children.

167

<div class="highlight-python"><div class="highlight"><pre>>>> mock = MagicMock()

168

>>> mock.method()

169

170

>>> mock.attribute.method(10, x=53)

171

172

>>> mock.mock_calls

173

[call.method(), call.attribute.method(10, x=53)]

174

</pre></div>

175

</div>

176

If you make an assertion about <cite>mock_calls</cite> and any unexpected methods

177

have been called, then the assertion will fail. This is useful because as well

178

as asserting that the calls you expected have been made, you are also checking

179

that they were made in the right order and with no additional calls:

180

You use the <tt class="xref py py-data docutils literal">call</tt> object to construct lists for comparing with

181

<cite>mock_calls</cite>:

182

<div class="highlight-python"><div class="highlight"><pre>>>> expected = [call.method(), call.attribute.method(10, x=53)]

183

>>> mock.mock_calls == expected

184

True

185

</pre></div>

186

</div>

187

</div>

188

189

<h3>Setting Return Values and Attributes<a class="headerlink" href="#setting-return-values-and-attributes" title="Permalink to this headline">¶</a></h3>

190

Setting the return values on a mock object is trivially easy:

191

<div class="highlight-python"><div class="highlight"><pre>>>> mock = Mock()

192

>>> mock.return_value = 3

193

>>> mock()

194

3

195

</pre></div>

196

</div>

197

Of course you can do the same for methods on the mock:

198

<div class="highlight-python"><div class="highlight"><pre>>>> mock = Mock()

199

>>> mock.method.return_value = 3

200

>>> mock.method()

201

3

202

</pre></div>

203

</div>

204

The return value can also be set in the constructor:

205

<div class="highlight-python"><div class="highlight"><pre>>>> mock = Mock(return_value=3)

206

>>> mock()

207

3

208

</pre></div>

209

</div>

210

If you need an attribute setting on your mock, just do it:

211

<div class="highlight-python"><div class="highlight"><pre>>>> mock = Mock()

212

>>> mock.x = 3

213

>>> mock.x

214

3

215

</pre></div>

216

</div>

217

Sometimes you want to mock up a more complex situation, like for example

218

<cite>mock.connection.cursor().execute(“SELECT 1”)</cite>. If we wanted this call to

219

return a list, then we have to configure the result of the nested call.

220

We can use <tt class="xref py py-data docutils literal">call</tt> to construct the set of calls in a “chained call” like

221

this for easy assertion afterwards:

222

<div class="highlight-python"><div class="highlight"><pre>>>> mock = Mock()

223

>>> cursor = mock.connection.cursor.return_value

224

>>> cursor.execute.return_value = ['foo']

225

>>> mock.connection.cursor().execute("SELECT 1")

226

['foo']

227

>>> expected = call.connection.cursor().execute("SELECT 1").call_list()

228

>>> mock.mock_calls

229

[call.connection.cursor(), call.connection.cursor().execute('SELECT 1')]

230

>>> mock.mock_calls == expected

231

True

232

</pre></div>

233

</div>

234

It is the call to <cite>.call_list()</cite> that turns our call object into a list of

235

calls representing the chained calls.

236

</div>

237

238

<h3>Raising exceptions with mocks<a class="headerlink" href="#raising-exceptions-with-mocks" title="Permalink to this headline">¶</a></h3>

239

A useful attribute is <tt class="xref py py-attr docutils literal">side_effect</tt>. If you set this to an

240

exception class or instance then the exception will be raised when the mock

241

is called.

242

<div class="highlight-python"><div class="highlight"><pre>>>> mock = Mock(side_effect=Exception('Boom!'))

243

>>> mock()

244

Traceback (most recent call last):

245

...

246

Exception: Boom!

247

</pre></div>

248

</div>

249

</div>

250

251

<h3>Side effect functions and iterables<a class="headerlink" href="#side-effect-functions-and-iterables" title="Permalink to this headline">¶</a></h3>

252

<cite>side_effect</cite> can also be set to a function or an iterable. The use case for

253

<cite>side_effect</cite> as an iterable is where your mock is going to be called several

254

times, and you want each call to return a different value. When you set

255

<cite>side_effect</cite> to an iterable every call to the mock returns the next value

256

from the iterable:

257

<div class="highlight-python"><div class="highlight"><pre>>>> mock = MagicMock(side_effect=[4, 5, 6])

258

>>> mock()

259

4

260

>>> mock()

261

5

262

>>> mock()

263

6

264

</pre></div>

265

</div>

266

For more advanced use cases, like dynamically varying the return values

267

depending on what the mock is called with, <cite>side_effect</cite> can be a function.

268

The function will be called with the same arguments as the mock. Whatever the

269

function returns is what the call returns:

270

<div class="highlight-python"><div class="highlight"><pre>>>> vals = {(1, 2): 1, (2, 3): 2}

271

>>> def side_effect(*args):

272

... return vals[args]

273

...

274

>>> mock = MagicMock(side_effect=side_effect)

275

>>> mock(1, 2)

276

1

277

>>> mock(2, 3)

278

2

279

</pre></div>

280

</div>

281

</div>

282

283

<h3>Creating a Mock from an Existing Object<a class="headerlink" href="#creating-a-mock-from-an-existing-object" title="Permalink to this headline">¶</a></h3>

284

One problem with over use of mocking is that it couples your tests to the

285

implementation of your mocks rather than your real code. Suppose you have a

286

class that implements <cite>some_method</cite>. In a test for another class, you

287

provide a mock of this object that also provides <cite>some_method</cite>. If later

288

you refactor the first class, so that it no longer has <cite>some_method</cite> - then

289

your tests will continue to pass even though your code is now broken!

290

<cite>Mock</cite> allows you to provide an object as a specification for the mock,

291

using the <cite>spec</cite> keyword argument. Accessing methods / attributes on the

292

mock that don’t exist on your specification object will immediately raise an

293

attribute error. If you change the implementation of your specification, then

294

tests that use that class will start failing immediately without you having to

295

instantiate the class in those tests.

296

<div class="highlight-python"><div class="highlight"><pre>>>> mock = Mock(spec=SomeClass)

297

>>> mock.old_method()

298

Traceback (most recent call last):

299

...

300

AttributeError: object has no attribute 'old_method'

301

</pre></div>

302

</div>

303

If you want a stronger form of specification that prevents the setting

304

of arbitrary attributes as well as the getting of them then you can use

305

<cite>spec_set</cite> instead of <cite>spec</cite>.

306

</div>

307

</div>

308

309

<h2>Patch Decorators<a class="headerlink" href="#patch-decorators" title="Permalink to this headline">¶</a></h2>

310

311

Note

312

With <cite>patch</cite> it matters that you patch objects in the namespace where they

313

are looked up. This is normally straightforward, but for a quick guide

314

read <a class="reference internal" href="patch.html#where-to-patch">where to patch</a>.

315

</div>

316

A common need in tests is to patch a class attribute or a module attribute,

317

for example patching a builtin or patching a class in a module to test that it

318

is instantiated. Modules and classes are effectively global, so patching on

319

them has to be undone after the test or the patch will persist into other

320

tests and cause hard to diagnose problems.

321

mock provides three convenient decorators for this: <cite>patch</cite>, <cite>patch.object</cite> and

322

<cite>patch.dict</cite>. <cite>patch</cite> takes a single string, of the form

323

<cite>package.module.Class.attribute</cite> to specify the attribute you are patching. It

324

also optionally takes a value that you want the attribute (or class or

325

whatever) to be replaced with. ‘patch.object’ takes an object and the name of

326

the attribute you would like patched, plus optionally the value to patch it

327

with.

328

<cite>patch.object</cite>:

329

<div class="highlight-python"><div class="highlight"><pre>>>> original = SomeClass.attribute

330

>>> @patch.object(SomeClass, 'attribute', sentinel.attribute)

331

... def test():

332

... assert SomeClass.attribute == sentinel.attribute

333

...

334

>>> test()

335

>>> assert SomeClass.attribute == original

336

337

>>> @patch('package.module.attribute', sentinel.attribute)

338

... def test():

339

... from package.module import attribute

340

... assert attribute is sentinel.attribute

341

...

342

>>> test()

343

</pre></div>

344

</div>

345

If you are patching a module (including <cite>__builtin__</cite>) then use <cite>patch</cite>

346

instead of <cite>patch.object</cite>:

347

<div class="highlight-python"><div class="highlight"><pre>>>> mock = MagicMock(return_value = sentinel.file_handle)

348

>>> with patch('__builtin__.open', mock):

349

... handle = open('filename', 'r')

350

...

351

>>> mock.assert_called_with('filename', 'r')

352

>>> assert handle == sentinel.file_handle, "incorrect file handle returned"

353

</pre></div>

354

</div>

355

The module name can be ‘dotted’, in the form <cite>package.module</cite> if needed:

356

<div class="highlight-python"><div class="highlight"><pre>>>> @patch('package.module.ClassName.attribute', sentinel.attribute)

357

... def test():

358

... from package.module import ClassName

359

... assert ClassName.attribute == sentinel.attribute

360

...

361

>>> test()

362

</pre></div>

363

</div>

364

A nice pattern is to actually decorate test methods themselves:

365

<div class="highlight-python"><div class="highlight"><pre>>>> class MyTest(unittest2.TestCase):

366

... @patch.object(SomeClass, 'attribute', sentinel.attribute)

367

... def test_something(self):

368

... self.assertEqual(SomeClass.attribute, sentinel.attribute)

369

...

370

>>> original = SomeClass.attribute

371

>>> MyTest('test_something').test_something()

372

>>> assert SomeClass.attribute == original

373

</pre></div>

374

</div>

375

If you want to patch with a Mock, you can use <cite>patch</cite> with only one argument

376

(or <cite>patch.object</cite> with two arguments). The mock will be created for you and

377

passed into the test function / method:

378

<div class="highlight-python"><div class="highlight"><pre>>>> class MyTest(unittest2.TestCase):

379

... @patch.object(SomeClass, 'static_method')

380

... def test_something(self, mock_method):

381

... SomeClass.static_method()

382

... mock_method.assert_called_with()

383

...

384

>>> MyTest('test_something').test_something()

385

</pre></div>

386

</div>

387

You can stack up multiple patch decorators using this pattern:

388

<div class="highlight-python"><div class="highlight"><pre>>>> class MyTest(unittest2.TestCase):

389

... @patch('package.module.ClassName1')

390

... @patch('package.module.ClassName2')

391

... def test_something(self, MockClass2, MockClass1):

392

... self.assertTrue(package.module.ClassName1 is MockClass1)

393

... self.assertTrue(package.module.ClassName2 is MockClass2)

394

...

395

>>> MyTest('test_something').test_something()

396

</pre></div>

397

</div>

398

When you nest patch decorators the mocks are passed in to the decorated

399

function in the same order they applied (the normal python order that

400

decorators are applied). This means from the bottom up, so in the example

401

above the mock for <cite>test_module.ClassName2</cite> is passed in first.

402

There is also <tt class="xref py py-func docutils literal">patch.dict()</tt> for setting values in a dictionary just

403

during a scope and restoring the dictionary to its original state when the test

404

ends:

405

<div class="highlight-python"><div class="highlight"><pre>>>> foo = {'key': 'value'}

406

>>> original = foo.copy()

407

>>> with patch.dict(foo, {'newkey': 'newvalue'}, clear=True):

408

... assert foo == {'newkey': 'newvalue'}

409

...

410

>>> assert foo == original

411

</pre></div>

412

</div>

413

<cite>patch</cite>, <cite>patch.object</cite> and <cite>patch.dict</cite> can all be used as context managers.

414

Where you use <cite>patch</cite> to create a mock for you, you can get a reference to the

415

mock using the “as” form of the with statement:

416

<div class="highlight-python"><div class="highlight"><pre>>>> class ProductionClass(object):

417

... def method(self):

418

... pass

419

...

420

>>> with patch.object(ProductionClass, 'method') as mock_method:

421

... mock_method.return_value = None

422

... real = ProductionClass()

423

... real.method(1, 2, 3)

424

...

425

>>> mock_method.assert_called_with(1, 2, 3)

426

</pre></div>

427

</div>

428

As an alternative <cite>patch</cite>, <cite>patch.object</cite> and <cite>patch.dict</cite> can be used as

429

class decorators. When used in this way it is the same as applying the

430

decorator indvidually to every method whose name starts with “test”.

431

For some more advanced examples, see the <a class="reference internal" href="examples.html#further-examples">Further Examples</a> page.

432

</div>

433

</div>

434

435

436

</div>

437

</div>

438

</div>

439

440

441

<h3><a href="index.html">Table Of Contents</a></h3>

442

<ul>

443

<li><a class="reference internal" href="#">Getting Started with Mock</a><ul>

444

<li><a class="reference internal" href="#using-mock">Using Mock</a><ul>

445

<li><a class="reference internal" href="#mock-patching-methods">Mock Patching Methods</a></li>

446

<li><a class="reference internal" href="#mock-for-method-calls-on-an-object">Mock for Method Calls on an Object</a></li>

447

<li><a class="reference internal" href="#mocking-classes">Mocking Classes</a></li>

448

<li><a class="reference internal" href="#naming-your-mocks">Naming your mocks</a></li>

449

<li><a class="reference internal" href="#tracking-all-calls">Tracking all Calls</a></li>

450

<li><a class="reference internal" href="#setting-return-values-and-attributes">Setting Return Values and Attributes</a></li>

451

<li><a class="reference internal" href="#raising-exceptions-with-mocks">Raising exceptions with mocks</a></li>

452

<li><a class="reference internal" href="#side-effect-functions-and-iterables">Side effect functions and iterables</a></li>

453

<li><a class="reference internal" href="#creating-a-mock-from-an-existing-object">Creating a Mock from an Existing Object</a></li>

454

</ul>

455

</li>

456

<li><a class="reference internal" href="#patch-decorators">Patch Decorators</a></li>

457

</ul>

458

</li>

459

</ul>

460

461

<h4>Previous topic</h4>

462

<a href="magicmock.html"

463

title="previous chapter">Mocking Magic Methods</a>

464

<h4>Next topic</h4>

465

<a href="examples.html"

466

title="next chapter">Further Examples</a>

467

468

469

<li><a href="_sources/getting-started.txt"

470

rel="nofollow">Show Source</a></li>

471

</ul>

472

473

<h3>Quick search</h3>

474

475

476

477

478

479

</form>

480

481

Enter search terms or a module, class or function name.

482

483

</div>

484

485

</div>

486

</div>

487

488

</div>

489

490

<h3>Navigation</h3>

491

<ul>

492

493

<a href="genindex.html" title="General Index"

494

>index</a></li>

495

496

<a href="examples.html" title="Further Examples"

497

>next</a> |</li>

498

499

<a href="magicmock.html" title="Mocking Magic Methods"

500

>previous</a> |</li>

501

<li><a href="index.html">Mock 1.0.1 documentation</a> »</li>

502

</ul>

503

</div>

504

505

506

Last updated on Nov 05, 2012.

507

Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.

508

</div>

509

</body>

510

</html>

b'\\ No newline at end of file'