Skip to content


Subversion checkout URL

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