This PR is a draft to propose a new function testModifySite

In most Yesod apps, there is an App datatype at the core of the application, holding all configuration and state for the app (e.g. settings, connection pools, IORefs, etc.). In the tests, this is setup on a per-test basis. This PR adds a new function, testModifySite, to modify that site in the middle of a test. This is the signature:

testModifySite :: YesodDispatch site => (site -> site) -> Middleware -> YesodExample site ()

Here are some use cases I'm imagining:

Testing how modifying settings changes behavior

The yesod scaffold comes with an AppSettings type you use to configure your app. An app may want to have a test like so:

it "only fires missiles if config allows it" $ do
  -- Many
  -- common
  -- lines
  -- of
  -- database
  -- configuration
  post FireMissilesR
  -- Assert nothing happens
  testModifySite (\site -> site { appSettings = (appSettings site) { appSettingsFireMissiles = True } }) id
  post FireMissilesR
  -- Assert missiles are fired

Changing out stubbed functions

The use case we have at work is we have a Stubs datatype in our app, and we use it to stub out functions. This looks roughly like so:

data App = App
  { appTestStubs :: Stubs
  ...
  }

data Stubs = Stubs 
  { stubMailerHandlerSendEmail :: forall m. (MonadIO m) => Maybe (m ())
  ...
  }

withStub :: (Monad m, HasApp m) => (Stubs -> Maybe (m a)) -> m a -> m a
withStub f realImpl = do
  stubs <- appTestStubs <$> getApp
  fromMaybe realImpl (f stubs)

handlerSendEmail message = withStub stubMailerHandlerSendEmail $ do
  -- Real implementation here

And in production, we set stubMailerHandlerSendEmail to Nothing, in which case our codebase uses the production implementation, but in tests we can use the stubbed function to customize behavior.

testModifySite would allow us to modify that stub in the middle of a test, so we could have tests like this:

it "records sent emails in the database if sending succeeds" $ do
  -- Lots
  -- of 
  -- test 
  -- setup
  post SendEmailR
  -- Assert that SentEmail record exists in database
  testModifySite (\site -> site { appTestStubs = (appTestStubs site) { stubMailerHandlerSendEmail = Just . liftIO $ throwIO EmailSendException } }) id
  post SendEmailR
  -- Assert that new email record was not created

A gotcha about this function is that the yedSite and yedApp parameters are tied together. So, once the site is modified, a new yedApp must be created from it using toWaiAppPlain then calling a new middleware function. I think this is OK though?

One could maybe drop the Middleware parameter of testModifySite, but the Middleware initially provided would have to be stored in YesodExampleData for later, which would be a breaking change. Also, it adds complexity to YesodExampleData just for the convenience of this function.

If this function sounds good, I'll add another function called testSetSite that outright replaces the site value.