Grepping ghc codebase for Template Haskell failure gets us this:

badIO :: String -> IO a
badIO op = do   { qReport True ("Can't do `" ++ op ++ "' in the IO monad")
                ; fail "Template Haskell failure" }

Which is kind of an awful error - the actual reason is interleaved within the test output, here.

I think what you'll want to do here is splice the doc into the file, and then you can write assertions on the doc in a spec. Like,

[d|
commentModelDoc :: String
commentModelDoc = 
  $(lift =<< getDoc (DeclDoc 'CommentModel))
|]

spec = describe "EntityHaddockSpec" $ do
    it "generates entity haddock" $ do
      commentModelDoc `shouldBe` "..."

Or, if you want a compilation failure, you could write the whole "test" in the splice.

module Test where
 
import Doc

do
    maybeDoc <- getDoc (DeclDoc 'CommentModel)
    case maybeDoc of
        Nothing -> reportError "Expected doc for CommentModel"
        Just doc -> do
            let expected = "..."
            when (doc /= expected) $ do
                reportError "Expected doc to be different..."

    pure [] -- to satisfy the `Q [Dec]` type for a top level splice   

But this is probably much less easy to write, and won't get you nice error message rendering. But it will fail faster, so idk. hspec-compilation is begging to be born I guess lol.

I've completed EntityHaddockSpec using the former method. However, the test output shows that it only finds the field comment added using putDoc - attempting to get the Haddock for CommentModel (added using withDecDoc) returns Nothing.

Now fixed - I'd put 'CommentModel (constructor Name) instead of ''CommentModel (type Name) in the splice.

Oh goodness - I guess you can write, like,

-- | commentary for type
data Thing = 
    -- | commentary for constructor
    MkThing 

Great catch 😄