Use TypedStub instead of ValueStub

Test possible issues around stub returning nil

spec/spectator/mocks/double_spec.cr

@@ -50,6 +50,24 @@ Spectator.describe Spectator::Double do
     end
   end
 
+  context "with nillable return type annotations" do
+    Spectator::Double.define(TestDouble) do
+      abstract_stub abstract def foo : String?
+      abstract_stub abstract def bar : Nil
+    end
+
+    let(foo_stub) { Spectator::ValueStub.new(:foo, nil).as(Spectator::Stub) }
+    let(bar_stub) { Spectator::ValueStub.new(:bar, nil).as(Spectator::Stub) }
+    subject(dbl) { TestDouble.new([foo_stub, bar_stub]) }
+
+    it "doesn't raise on nil" do
+      aggregate_failures do
+        expect(dbl.foo).to be_nil
+        expect(dbl.bar).to be_nil
+      end
+    end
+  end
+
   context "with common object methods" do
     subject(dbl) do
       EmptyDouble.new([

spec/spectator/mocks/null_double_spec.cr

@@ -58,6 +58,24 @@ Spectator.describe Spectator::NullDouble do
     end
   end
 
+  context "with nillable return type annotations" do
+    Spectator::NullDouble.define(TestDouble) do
+      abstract_stub abstract def foo : String?
+      abstract_stub abstract def bar : Nil
+    end
+
+    let(foo_stub) { Spectator::ValueStub.new(:foo, nil).as(Spectator::Stub) }
+    let(bar_stub) { Spectator::ValueStub.new(:bar, nil).as(Spectator::Stub) }
+    subject(dbl) { TestDouble.new([foo_stub, bar_stub]) }
+
+    it "doesn't raise on nil" do
+      aggregate_failures do
+        expect(dbl.foo).to be_nil
+        expect(dbl.bar).to be_nil
+      end
+    end
+  end
+
   context "with common object methods" do
     subject(dbl) do
       EmptyDouble.new([

src/spectator/mocks/stubbable.cr

@@ -52,6 +52,9 @@ module Spectator
     # This method can also raise an error if it's impossible to return something.
     abstract def _spectator_abstract_stub_fallback(call : MethodCall, type)
 
+    # Utility method returning the stubbed type's name formatted for user output.
+    abstract def _spectator_stubbed_name : String
+
     # Redefines a method to accept stubs.
     #
     # The *method* should be a `Def`.
@@ -101,12 +104,21 @@ module Spectator
 
         if %stub = _spectator_find_stub(%call)
           {% if !method.abstract? %}
-            %stub.as(::Spectator::ValueStub(typeof({{original}}))).value
+            %stub.as(::Spectator::TypedStub(typeof({{original}}))).value
           {% elsif method.return_type %}
-            if %cast = %stub.as?(::Spectator::ValueStub({{method.return_type}}))
+            if %typed = %stub.as?(::Spectator::TypedStub({{method.return_type}}))
-              %cast.value
+              %typed.value
             else
-              %stub.value.as({{method.return_type}})
+              %value = %stub.value
+              if %cast = %value.as?({{method.return_type}})
+                %cast
+              else
+                {% if method.return_type.resolve >= Nil %}
+                  nil
+                {% else %}
+                  raise TypeCastError.new("#{_spectator_stubbed_name} received message #{%call} and is attempting to return a `#{%value.class}`, but returned type must be `{{method.return_type}}`.")
+                {% end %}
+              end
             end
           {% else %}
             %stub.value
@@ -165,10 +177,19 @@ module Spectator
 
         if %stub = _spectator_find_stub(%call)
           {% if method.return_type %}
-            if %cast = %stub.as?(::Spectator::ValueStub({{method.return_type}}))
+            if %typed = %stub.as?(::Spectator::TypedStub({{method.return_type}}))
-              %cast.value
+              %typed.value
             else
-              %stub.value.as({{method.return_type}})
+              %value = %stub.value
+              if %cast = %value.as?({{method.return_type}})
+                %cast
+              else
+                {% if method.return_type.resolve >= Nil %}
+                  nil
+                {% else %}
+                  raise TypeCastError.new("#{_spectator_stubbed_name} received message #{%call} and is attempting to return a `#{%value.class}`, but returned type must be `{{method.return_type}}`.")
+                {% end %}
+              end
             end
           {% else %}
             %stub.value