title: How are integration tests written for interacting with external API?
body: <h2>First up, where my knowledge is at:</h2>
  
  <p><em>Unit Tests</em> are those which test a small piece of code (single methods, mostly). </p>
  
  <p><em>Integration Tests</em> are those which test the interaction between multiple areas of code (which hopefully already have their own Unit Tests). Sometimes, parts of the code under test requires other code to act in a particular way. This is where Mocks &amp; Stubs come in. So, we mock/stub out a part of the code to perform very specifically. This allows our Integration Test to run predictably without side effects.</p>
  
  <p>All tests should be able to be run stand-alone without data sharing. If data sharing is necessary, this is a sign the system isn't decoupled enough.</p>
  
  <h2>Next up, the situation I am facing:</h2>
  
  <p>When interacting with an external API (specifically, a RESTful API that will modify live data with a POST request), I understand we can (should?) mock out the interaction with that API (more eloquently stated in <a href="https://stackoverflow.com/questions/559092/how-can-mocking-external-services-improve-unit-tests/559177#559177">this answer</a>) for an Integration Test. I also understand we can Unit Test the individual components of interacting with that API (constructing the request, parsing the result, throwing errors, etc). What I don't get is how to actually go about this.</p>
  
  <h2>So, finally: My question(s).</h2>
  
  <p>How do I test my interaction with an external API that has side effects?</p>
  
  <p>A perfect example is <a href="http://code.google.com/apis/shopping/content/getting-started/usingapi-products.html" rel="noreferrer">Google's Content API for shopping</a>. To be able to perform the task at hand, it requires a decent amount of prep work, then performing the actual request, then analysing the return value. Some of this is <a href="https://groups.google.com/group/google-content-api-for-shopping/browse_thread/thread/ad6d1f482a7cae4d#msg_d4ab56ab47877fba" rel="noreferrer">without any 'sandbox' environment</a>.</p>
  
  <p>The code to do this generally has quite a few layers of abstraction, something like:</p>
  
  <pre class="lang-php prettyprint-override"><code>&lt;?php
  class Request
  {
      public function setUrl(..){ /* ... */ }
      public function setData(..){ /* ... */ }
      public function setHeaders(..){ /* ... */ }
      public function execute(..){
          // Do some CURL request or some-such
      }   
      public function wasSuccessful(){
          // some test to see if the CURL request was successful
      }   
  }
  
  class GoogleAPIRequest
  {
      private $request;
      abstract protected function getUrl();
      abstract protected function getData();
  
      public function __construct() {
          $this-&gt;request = new Request();
          $this-&gt;request-&gt;setUrl($this-&gt;getUrl());
          $this-&gt;request-&gt;setData($this-&gt;getData());
          $this-&gt;request-&gt;setHeaders($this-&gt;getHeaders());
      }   
  
      public function doRequest() {
          $this-&gt;request-&gt;execute();
      }   
      public function wasSuccessful() {
          return ($this-&gt;request-&gt;wasSuccessful() &amp;&amp; $this-&gt;parseResult());
      }   
      private function parseResult() {
          // return false when result can't be parsed
      }   
  
      protected function getHeaders() {
          // return some GoogleAPI specific headers
      }   
  }
  
  class CreateSubAccountRequest extends GoogleAPIRequest
  {
      private $dataObject;
  
      public function __construct($dataObject) {
          parent::__construct();
          $this-&gt;dataObject = $dataObject;
      }   
      protected function getUrl() {
          return "http://...";
      }
      protected function getData() {
          return $this-&gt;dataObject-&gt;getSomeValue();
      }
  }
  
  class aTest
  {
      public function testTheRequest() {
          $dataObject = getSomeDataObject(..);
          $request = new CreateSubAccountRequest($dataObject);
          $request-&gt;doRequest();
          $this-&gt;assertTrue($request-&gt;wasSuccessful());
      }
  }
  ?&gt;
  </code></pre>
  
  <p><em>Note: This is a PHP5 / PHPUnit example</em></p>
  
  <p>Given that <code>testTheRequest</code> is the method called by the test suite, the example will execute a live request.</p>
  
  <p>Now, this live request will (hopefully, provided everything went well) do a POST request that has the side effect of altering live data.</p>
  
  <p>Is this acceptable? What alternatives do I have? I can't see a way to mock out the Request object for the test. And even if I did, it would mean setting up results / entry points for every possible code path that Google's API accepts (which in this case would have to be found by trial and error), but would allow me the use of fixtures.</p>
  
  <p>A further extension is when certain requests rely on certain data being Live already. Using the Google Content API as an example again, to add a Data Feed to a Sub Account, the Sub Account must already exist.</p>
  
  <p>One approach I can think of is the following steps;</p>
  
  <ol>
  <li>In <code>testCreateAccount</code>
  
  <ol>
  <li>Create a sub-account</li>
  <li>Assert the sub-account was created</li>
  <li>Delete the sub-account</li>
  </ol></li>
  <li>Have <code>testCreateDataFeed</code> depend on <code>testCreateAccount</code> not having any errors
  
  <ol>
  <li>In <code>testCreateDataFeed</code>, create a new account</li>
  <li>Create the data feed</li>
  <li>Assert the data feed was created</li>
  <li>Delete the data feed</li>
  <li>Delete the sub-account</li>
  </ol></li>
  </ol>
  
  <p>This then raises the further question; how do I test the deletion of accounts / data feeds? <code>testCreateDataFeed</code> feels dirty to me - What if creating the data feed fails? The test fails, therefore the sub-account is never deleted... I can't test deletion without creation, so do I write another test (<code>testDeleteAccount</code>) that relies on <code>testCreateAccount</code> before creating then deleting an account of its own (since data shouldn't be shared between tests).</p>
  
  <h2>In Summary</h2>
  
  <ul>
  <li>How do I test interacting with an external API that effects live data?</li>
  <li>How can I mock / stub objects in an Integration test when they're hidden behind layers of abstraction?</li>
  <li>What do I do when a test fails and the live data is left in an inconsistent state?</li>
  <li>How <em>in code</em> do I actually go about doing all this?</li>
  </ul>
  
  <hr>
  
  <p>Related:</p>
  
  <ul>
  <li><a href="https://stackoverflow.com/questions/559092/how-can-mocking-external-services-improve-unit-tests/559177">How can mocking external services improve unit tests?</a></li>
  <li><a href="https://stackoverflow.com/questions/7380903/writing-unit-tests-for-a-rest-ful-api">Writing unit tests for a REST-ful API</a></li>
  </ul>