title: How does RxJava doOnError and onErrorReturn work?
body: <p>I made these unit tests, and the outcome is not what I expected at all:</p>
  
  <pre><code>// This one outputs "subscribe.onError" 
  @Test
  public void observable_doOnError_subscribingToError() throws InterruptedException {
      Observable&lt;String&gt; obs = getErrorProducingObservable();
      obs.doOnError(throwable -&gt; System.out.println("doOnError"));
      obs.subscribeOn(Schedulers.immediate()).observeOn(Schedulers.immediate()).subscribe(
          s -&gt; {},
          error -&gt; System.out.println("subscribe.onError")
      );
      Thread.sleep(300);
  }
  
  // This one outputs "subscribe.onError" 
  @Test
  public void observable_onErrorReturn() throws InterruptedException {
      Observable&lt;String&gt; obs = getErrorProducingObservable();
      obs.onErrorReturn(throwable -&gt; "Yeah I got this");
      obs.subscribeOn(Schedulers.immediate()).observeOn(Schedulers.immediate()).subscribe(
          s -&gt; System.out.println("got: " + s),
          error -&gt; System.out.println("subscribe.onError")
      );
      Thread.sleep(300);
  }
  
  private Observable&lt;String&gt; getErrorProducingObservable()  {
      return Observable.create(subscriber -&gt; {
          subscriber.onError(new RuntimeException("Somebody set up us the bomb"));
      });
  }
  </code></pre>
  
  <p>So both output "subscribe.onError" - neither <code>doOnError</code> nor <code>onErrorReturn</code> seems to be called. </p>
  
  <p><code>doOnError</code>is documented as:</p>
  
  <blockquote>
    <p>Modifies the source Observable so that it invokes an action if it calls onError.</p>
  </blockquote>
  
  <p>I'm not sure how to intepret that, but I expected either "doOnError" to be output or "doOnError" followed by "subscribe.onError". </p>
  
  <p><code>onErrorReturn</code> is documented as :</p>
  
  <blockquote>
    <p>Instructs an Observable to emit an item (returned by a specified function) rather than invoking onError if it encounters an error.</p>
  </blockquote>
  
  <p>Hence I was expecting "got: Yeah I got this" as output from the latter test.</p>
  
  <p>What gives? </p>