Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 103 lines (81 sloc) 4.811 kB
f4ff6ae @acoulton Updated readme with information on roadmap, tests, docs and contributing
authored
1 # Mimic
2
3 Mimic is a module for [Kohana Framework v3.2 and up](http://kohanaframework.org)
4 that allows easy mocking and testing of an application's interaction with external
5 web services.
6
7 If you've used the [VCR module for Ruby](https://github.com/myronmarston/vcr),
8 you'll recognise the concept. By default,
9 Mimic intercepts all external requests and throws an exception. When recording mode
10 is enabled, Mimic executes the external request and records the response (complete
11 with headers and response status) to disk. Future requests to the external resource
12 will return the response that has been stored on disk, allowing increased performance
13 and more importantly an idempotent implementation of unit and functional tests with
14 a minimum of configuration or mocking code.
15
16 ## Matching requests
17 Outgoing requests can be matched by a variety of characteristics:
18
19 * URL
20 * HTTP Method
21 * URI Parameters
22 * Request Headers
23
24 By default, Mimic records all of these. The recording files can then be easily
25 modified to allow looser matching of requests (useful if you want to return the
26 same response in multiple request scenarios).
27
28 ## Scenarios
29 Mimic supports multiple named scenarios (nothing more complex than a separate
30 set of disk paths where request/response files are stored) so that you can model
31 different behaviour for the same request URL - for example an error condition, or
32 the difference between authenticated and anonymous requests. This is broadly
33 equivalent to VCR's "Cassettes".
34
35 ## Tweaking responses
36 Requests and responses are stored in easily editable formats, allowing you to tweak
37 both the request and response for a variety of scenarios. For example, you might
38 want to customise the response to fake an error condition that is difficult
39 to trigger from the client side.
40
41 By default, responses with supported content types (currently XML and JSON) will
42 be passed through a formatter before saving. The formatter adds additional whitespace
43 so that responses are human-readable and more easily edited, diffed, etc.
44
45 ***If you are performing authenticated requests or accessing non-public content,
46 you should always review the recording files by hand and remove any passwords,
47 authentication tokens or private content before committing to a source code
48 repository!***
49
50 ## Verifying application behaviour
51 In addition to replaying "canned" responses, Mimic keeps a history of requests
52 executed and responses returned. You can access the history from your test cases
53 to verify:
54
55 * That an expected pattern of requests were sent (for example, that a given
56 parameter was present in an outbound query string)
57 * That an expected number of requests were sent
58 * Pretty much anything else you can think of.
59
60 ## Unit Tests
61 Mimic is fully unit tested (PHPUnit tests are included in this repository). The
62 tests make use of the [vfsStream](https://github.com/mikey179/vfsStream)
63 virtual filesystem library for mocking and verifying file system interactions.
64
65 To run the tests on a standard Kohana installation (with the unittest module)
66 just run the following from the base folder:
67
68 phpunit --bootstrap=modules/unittest/bootstrap.php --group=mimic modules/unittest/tests.php
69
70 ## Further Documentation
71 Is included with the module, integrated into the Kohana online userguide.
72
73 ## Roadmap and stability
74 Mimic is currently under initial development. Intended functionality includes:
75
76 * Formatter support for Javascript and HTML.
77 * Support for matching on body content of POST/PUT requests
78 * PHPUnit base testcase class integrating Mimic and offering common assertions
79 * A self-contained Kohana application using Mimic to power a proxy server controlled
80 through an API. This can be used for isolated functional testing with tools like
81 Behat (the proxy will come with a set of useful Behat step definitions). You will
82 configure your server's internet routing table to pass all outbound requests to
83 the Mimic Proxy, meaning your production application code can be fully exercised
84 against a set of mocked web request/responses and allowing you to share web scenarios
85 between unit and functional tests.
86
87
88 ## Licence
89 Mimic © 2011 [Ingenerator](http://www.ingenerator.com) and is
90 released under the [Kohana Licence](http://kohanaframework.org/licence)
91
92 ## Issues and contributions
93 Bug reports and feature requests are welcome via the project's Github issue tracker,
94 preferably with a pull request attached.
95
96 Pull requests should:
97
98 * be targeted against the relevant develop branch
99 * be contained in a separate topic/bug branch in your forked respository (in case
100 further commits are required to complete your solution)
101 * generally speaking, include a unit test or new dataset for an existing test that
102 fails before your new code is merged and passes afterwards
103 * adopt the Kohana coding standards
Something went wrong with that request. Please try again.