Debian Codegraph @

test/Data/Acid/StateMachineTest.hs

raw
1 {-# LANGUAGE CPP #-}
2 {-# LANGUAGE ExistentialQuantification #-}
3 {-# LANGUAGE FlexibleContexts #-}
4 {-# LANGUAGE RecordWildCards #-}
5 {-# LANGUAGE ScopedTypeVariables #-}
6 {-# LANGUAGE TemplateHaskell #-}
7 {-# LANGUAGE TypeFamilies #-}
8
9 -- | This module provides a general framework for state-machine testing of
10 -- acid-state components. It needs to be instantiated with a
11 -- particular acid-state component to get a concrete test.
12 module Data.Acid.StateMachineTest
13 ( acidUpdate
14 , acidUpdateMayFail
15 , acidUpdateCheckFail
16 , acidQuery
17 , acidQueryMayFail
18 , acidQueryCheckFail
19 , acidStateSequentialProperty
20 , acidStateParallelProperty
21 , restoreOldStateProperty
22 , acidStateInterface
23 , AcidStateInterface(..)
24
25 , Model(..)
26 , open
27 , close
28 , checkpoint
29 , checkpointClose
30 , kill
31
32 -- * Testing exceptions
33 , TransactionError(..)
34 , failQuery
35 , failUpdate
36 , Bomb(..)
37 , explodeWHNF
38 , explodeNF
39 , genBomb
40 ) where
41
42 import Control.DeepSeq
43 import Control.Exception (Exception, IOException, throw, catch, try, evaluate)
44 import Control.Monad.IO.Class ( MonadIO(..) )
45 import Control.Monad.State ( State, evalState, execState )
46 import qualified Data.Acid as Acid
47 import qualified Data.Acid.Common as Common
48 import qualified Data.Acid.Core as Core
49 import qualified Data.Acid.Local as Local
50 import Data.Maybe
51 import qualified Data.SafeCopy as SafeCopy
52 import Data.Typeable
53 import Hedgehog
54 import qualified Hedgehog.Gen as Gen
55 import System.Directory (removeDirectoryRecursive, removeFile)
56 import System.IO.Unsafe (unsafePerformIO)
57
58 -- | Exception to be thrown when a query or update fails.
59 --
60 -- At the moment the only way to implement failing transactions is by
61 -- throwing an exception from pure code. The state machine tests
62 -- assume that all failures use 'failQuery' or 'failUpdate', which
63 -- throw this exception. Thus we can catch this exception in cases
64 -- where transaction failures are accepted.
65 --
66 -- Even if acid-state provided a pure way to throw and catch errors in
67 -- the 'Update' and 'Query' monads, we would still need to test that
68 -- it correctly handles exceptions thrown during transactions.
69 data TransactionError = TransactionError String
70 deriving Show
71 instance Exception TransactionError
72
73 -- | Cause a 'Query' to fail in a (possibly) expected manner. See
74 -- 'acidQueryMayFail' and 'acidQueryCheckFail'.
75 failQuery :: String -> Acid.Query s a
76 failQuery s = throw (TransactionError s)
77
78 -- | Cause an 'Update' to fail in a (possibly) expected manner. See
79 -- 'acidUpdateMayFail' and 'acidUpdateCheckFail'.
80 failUpdate :: String -> Acid.Update s a
81 failUpdate s = throw (TransactionError s)
82
83 -- | Container for exceptions thrown from pure code. This is
84 -- intended for use as an argument to transactions, for testing
85 -- transactions that cannot be serialised.
86 data Bomb = Bomb { unBomb :: Int }
87
88 instance NFData Bomb where
89 rnf (Bomb n) = rnf n
90
91 -- | Slightly hacky 'Show' instance that will attempt to show
92 -- something sensible even if evaluating the 'Bomb' throws an
93 -- exception.
94 instance Show Bomb where
95 show b = "(Bomb " ++ s ++ ")"
96 where
97 s = unsafePerformIO $ evaluate (show (unBomb b)) `catch` \ TransactionError{} -> return "(exploded)"
98
99 -- | Throw an exception when evaluated to WHNF.
100 explodeWHNF :: Bomb
101 explodeWHNF = throw (TransactionError "boom!")
102
103 -- | Throw an exception when evaluated to NF (but not when
104 -- evaluated to WHNF).
105 explodeNF :: Bomb
106 explodeNF = Bomb (throw (TransactionError "boom!"))
107
108 -- | Generate a bomb that may or may not explode (throw an exception)
109 -- when evaluated.
110 genBomb :: Gen Bomb
111 genBomb = Gen.element [Bomb 0, Bomb 1, Bomb 2, Bomb 3, explodeWHNF, explodeNF]
112
113 $(SafeCopy.deriveSafeCopy 0 'SafeCopy.base ''Bomb)
114
115
116 -- | Model of an acid-state component, for state machine property
117 -- testing. We start in 'StateAbsent' and can transition to
118 -- 'StateOpen' by opening the state for the first time. Thereafter we
119 -- can transition between 'StateOpen' and 'StateClosed' by opening and
120 -- closing the state. Both of the latter keep track of the current
121 -- value of the state.
122 data Model s (v :: * -> *)
123 = StateAbsent -- ^ State is not present on disk
124 | StateClosed s -- ^ State is present on disk, but not in memory
125 | StateOpen s (Var (Opaque (Acid.AcidState s)) v) -- ^ State is open in memory
126
127 -- | Return the handle to the acid-state component if it is open, or
128 -- return 'Nothing' if it is closed or absent.
129 modelHandle :: Model s v -> Maybe (Var (Opaque (Acid.AcidState s)) v)
130 modelHandle (StateOpen _ hdl) = Just hdl
131 modelHandle _ = Nothing
132
133 -- | Is the state currently open?
134 isOpen :: Model s v -> Bool
135 isOpen = isJust . modelHandle
136
137 -- | Return the current value of the state, if it is present.
138 modelValue :: Model s v -> Maybe s
139 modelValue (StateClosed s) = Just s
140 modelValue (StateOpen s _) = Just s
141 modelValue StateAbsent = Nothing
142
143
144 -- | Description of the interface for performing
145 -- meta-operations on an acid-state, such as opening, closing and
146 -- checkpointing it. The testing code is abstracted over this
147 -- interface so that we can substitute alternate serialisation
148 -- backends.
149 data AcidStateInterface s =
150 (Typeable s, Acid.IsAcidic s, Show s)
151 => AcidStateInterface
152 { openState :: s -> IO (Acid.AcidState s)
153 , closeState :: Acid.AcidState s -> IO ()
154 , checkpointState :: Acid.AcidState s -> IO ()
155 , checkpointCloseState :: Acid.AcidState s -> IO ()
156 , resetState :: IO ()
157 , statePath :: FilePath
158 }
159
160 -- | Standard implementation of the acid-state interface, using
161 -- 'SafeCopy'-based serialisation.
162 --
163 -- This takes the path to the state directory as an argument.
164 -- Warning: this path will be deleted/overwritten!
165 acidStateInterface :: (Acid.IsAcidic s, SafeCopy.SafeCopy s, Typeable s, Show s)
166 => FilePath -> AcidStateInterface s
167 acidStateInterface fp =
168 AcidStateInterface { openState = Acid.openLocalStateFrom fp
169 , closeState = Acid.closeAcidState
170 , checkpointState = Acid.createCheckpoint
171 , checkpointCloseState = Local.createCheckpointAndClose
172 , resetState = removeDirectoryRecursive fp
173 `catch` (\ (_ :: IOException) -> return ())
174 , statePath = fp
175 }
176
177
178 data Open s (v :: * -> *) = Open s
179 deriving Show
180
181 #if MIN_VERSION_hedgehog(1,1,0)
182 instance FunctorB (Open s) where
183 bmap _ (Open s) = Open s
184 instance TraversableB (Open s) where
185 btraverse _ (Open s) = pure (Open s)
186 #else
187 instance HTraversable (Open s) where
188 htraverse _ (Open s) = pure (Open s)
189 #endif
190
191 -- | Command to open the state, given the interface to use and a
192 -- generator for possible initial state values.
193 open :: MonadIO m => AcidStateInterface s -> Gen s -> Command Gen m (Model s)
194 open AcidStateInterface{..} gen_initial_state =
195 Command gen execute [ Require require, Update update ]
196 where
197 require model _ = not (isOpen model)
198
199 gen StateAbsent = Just (Open <$> gen_initial_state)
200 gen StateClosed{} = Just (Open <$> gen_initial_state)
201 gen StateOpen{} = Nothing
202
203 execute (Open initial_state) = liftIO (Opaque <$> openState initial_state)
204
205 update StateAbsent (Open s) hdl = StateOpen s hdl
206 update (StateClosed s) (Open _) hdl = StateOpen s hdl
207 update StateOpen{} _ _ = error "open: state already open!"
208
209
210 data WithState s (v :: * -> *) = WithState String (Var (Opaque (Acid.AcidState s)) v)
211 deriving (Show)
212
213 #if MIN_VERSION_hedgehog(1,1,0)
214 instance FunctorB (WithState s) where
215 bmap k (WithState l v) = WithState l (bmap k v)
216 instance TraversableB (WithState s) where
217 btraverse k (WithState l v) = WithState l <$> btraverse k v
218 #else
219 instance HTraversable (WithState s) where
220 htraverse k (WithState l v) = WithState l <$> htraverse k v
221 #endif
222
223 genWithState :: Applicative g => String -> Model s v -> Maybe (g (WithState s v))
224 genWithState l model = pure . WithState l <$> modelHandle model
225
226 -- | Command to close the state.
227 close :: MonadIO m => AcidStateInterface s -> Command Gen m (Model s)
228 close AcidStateInterface{..} =
229 Command (genWithState "Close") execute [ Require require, Update update ]
230 where
231 require model _ = isOpen model
232
233 execute (WithState _ (Var (Concrete (Opaque st)))) = liftIO (closeState st)
234 update (StateOpen s _) _ _ = StateClosed s
235 update _ _ _ = error "close: not open"
236
237 -- | Command to take a checkpoint of the state.
238 checkpoint :: MonadIO m => AcidStateInterface s -> Command Gen m (Model s)
239 checkpoint AcidStateInterface{..} =
240 Command (genWithState "checkpoint") execute [ Require require ]
241 where
242 require model _ = isOpen model
243 execute (WithState _ (Var (Concrete (Opaque st)))) = liftIO (checkpointState st)
244
245 -- | Command to take a checkpoint and close the state, as a single atomic action.
246 checkpointClose :: MonadIO m => AcidStateInterface s -> Command Gen m (Model s)
247 checkpointClose AcidStateInterface{..} =
248 Command (genWithState "checkpointClose") execute [ Require require, Update update ]
249 where
250 require model _ = isOpen model
251 execute (WithState _ (Var (Concrete (Opaque st)))) = liftIO (checkpointCloseState st)
252 update (StateOpen s _) _ _ = StateClosed s
253 update _ _ _ = error "checkpointClose: not open"
254
255 -- | Command to simulate killing the process without closing the
256 -- state. This does not actually stop the old thread, though.
257 --
258 -- The lock file is removed so that the state can be reopened
259 -- (otherwise further commands would immediately fail).
260 kill :: MonadIO m => AcidStateInterface s -> Command Gen m (Model s)
261 kill AcidStateInterface{..} =
262 Command (genWithState "kill") execute [ Require require, Update update ]
263 where
264 require model _ = isOpen model
265 execute WithState{} = liftIO $ removeFile (statePath ++ "/open.lock")
266 update (StateOpen s _) _ _ = StateClosed s
267 update _ _ _ = error "kill: not open"
268
269
270
271 data AcidCommand s e (v :: * -> *) = AcidCommand e (Var (Opaque (Acid.AcidState s)) v)
272 deriving (Show)
273
274 #if MIN_VERSION_hedgehog(1,1,0)
275 instance FunctorB (AcidCommand s e) where
276 bmap k (AcidCommand e s) = AcidCommand e (bmap k s)
277 instance TraversableB (AcidCommand s e) where
278 btraverse k (AcidCommand e s) = AcidCommand e <$> btraverse k s
279 #else
280 instance HTraversable (AcidCommand s e) where
281 htraverse k (AcidCommand e s) = AcidCommand e <$> htraverse k s
282 #endif
283
284 -- | Translate an acid-state update into a command that executes the
285 -- update, given a generator of inputs. If the update fails, the
286 -- property as a whole fails.
287 acidUpdate :: forall s e m .
288 ( Acid.IsAcidic s
289 , Acid.EventState e ~ s
290 , Acid.UpdateEvent e
291 , Show e
292 , NFData e
293 , Eq (Acid.EventResult e)
294 , Show (Acid.EventResult e)
295 , Typeable (Acid.EventResult e)
296 , MonadIO m
297 )
298 => Gen e -> Command Gen m (Model s)
299 acidUpdate = acidUpdateCheckFail (\ _ _ _ _ -> failure)
300
301 -- | Translate an acid-state update into a command that executes the
302 -- update, given a generator of inputs. If the update fails, the
303 -- property as a whole succeeds.
304 acidUpdateMayFail :: forall s e m .
305 ( Acid.IsAcidic s
306 , Acid.EventState e ~ s
307 , Acid.UpdateEvent e
308 , Show e
309 , NFData e
310 , Eq (Acid.EventResult e)
311 , Show (Acid.EventResult e)
312 , Typeable (Acid.EventResult e)
313 , MonadIO m
314 )
315 => Gen e -> Command Gen m (Model s)
316 acidUpdateMayFail = acidUpdateCheckFail (\ _ _ _ _ -> return ())
317
318 -- | Translate an acid-state update into a command that executes the
319 -- update, given a generator of inputs. If the update fails, the
320 -- given predicate is tested on the old and new states, the event and
321 -- the 'TransactionError' exception.
322 acidUpdateCheckFail :: forall s e m .
323 ( Acid.IsAcidic s
324 , Acid.EventState e ~ s
325 , Acid.UpdateEvent e
326 , Show e
327 , NFData e
328 , Eq (Acid.EventResult e)
329 , Show (Acid.EventResult e)
330 , Typeable (Acid.EventResult e)
331 , MonadIO m
332 )
333 => (s -> s -> e -> TransactionError -> Test ())
334 -> Gen e -> Command Gen m (Model s)
335 acidUpdateCheckFail allow_failure gen_event =
336 Command gen execute [ Require require, Update update, Ensure ensure ]
337 where
338 -- Generate updates only when state is open
339 gen :: Model s Symbolic -> Maybe (Gen (AcidCommand s e Symbolic))
340 gen model = case modelHandle model of
341 Just st -> Just (AcidCommand <$> gen_event <*> pure st)
342 Nothing -> Nothing
343
344 -- Execute a concrete update directly using acid-state
345 execute :: AcidCommand s e Concrete -> m (Either TransactionError (Acid.EventResult e))
346 execute (AcidCommand e (Var (Concrete (Opaque st)))) = liftIO (try (Acid.update st e))
347
348 -- Shrinking updates requires the state to be open
349 require :: Model s Symbolic -> AcidCommand s e Symbolic -> Bool
350 require model _ = isOpen model
351
352 -- Updates cause the model state to be updated. This needs
353 -- 'unsafePerformIO' because the update function must be pure, but
354 -- we need to deal with the possibility of the transaction
355 -- throwing a 'TransactionError' exception, in which case the
356 -- state of the model should not change. We need to deepseq the
357 -- update event itself, in case it contains a nested error that
358 -- will show up during serialisation but is not forced by
359 -- executing the transaction.
360 update :: Model s v
361 -> AcidCommand s e v
362 -> Var (Either TransactionError (Acid.EventResult e)) v
363 -> Model s v
364 update (StateOpen s hdl) (AcidCommand c _) _ =
365 unsafePerformIO $ do
366 s' <- evaluate (c `deepseq` execState (lookupMethod c) s)
367 `catch` \ (_ :: TransactionError) -> return s
368 return (StateOpen s' hdl)
369 update _ _ _ = error "acidUpdate: state not open"
370
371 -- Evaluating the update directly on the model value of the old
372 -- state should give the same result
373 ensure :: Model s Concrete
374 -> Model s Concrete
375 -> AcidCommand s e Concrete
376 -> Either TransactionError (Acid.EventResult e)
377 -> Test ()
378 ensure model0 model1 (AcidCommand c _) (Left e) = case (modelValue model0, modelValue model1) of
379 (Just v0, Just v1) -> allow_failure v0 v1 c e
380 _ -> failure
381 ensure model _ (AcidCommand c _) (Right o) = case modelValue model of
382 Just v -> evalState (lookupMethod c) v === o
383 Nothing -> failure
384
385 -- | Translate an acid-state query into a command that executes the
386 -- query, given a generator of inputs. If the query fails, the
387 -- property as a whole fails.
388 acidQuery :: forall s e m .
389 ( Acid.IsAcidic s
390 , Acid.EventState e ~ s
391 , Acid.QueryEvent e
392 , Show e
393 , Eq (Acid.EventResult e)
394 , Show (Acid.EventResult e)
395 , Typeable (Acid.EventResult e)
396 , MonadIO m
397 , Eq s
398 , Show s
399 )
400 => Gen e -> Command Gen m (Model s)
401 acidQuery = acidQueryCheckFail (\ _ _ _ -> failure)
402
403 -- | Translate an acid-state query into a command that executes the
404 -- query, given a generator of inputs. If the query fails, the
405 -- property as a whole succeeds.
406 acidQueryMayFail :: forall s e m .
407 ( Acid.IsAcidic s
408 , Acid.EventState e ~ s
409 , Acid.QueryEvent e
410 , Show e
411 , Eq (Acid.EventResult e)
412 , Show (Acid.EventResult e)
413 , Typeable (Acid.EventResult e)
414 , MonadIO m
415 , Eq s
416 , Show s
417 )
418 => Gen e -> Command Gen m (Model s)
419 acidQueryMayFail = acidQueryCheckFail (\ _ _ _ -> return ())
420
421 -- | Translate an acid-state query into a command that executes the
422 -- query, given a generator of inputs. If the query fails, the given
423 -- predicate is tested on the state, the event and the
424 -- 'TransactionError' exception.
425 acidQueryCheckFail :: forall s e m .
426 ( Acid.IsAcidic s
427 , Acid.EventState e ~ s
428 , Acid.QueryEvent e
429 , Show e
430 , Eq (Acid.EventResult e)
431 , Show (Acid.EventResult e)
432 , Typeable (Acid.EventResult e)
433 , MonadIO m
434 , Eq s
435 , Show s
436 )
437 => (s -> e -> TransactionError -> Test ()) -> Gen e -> Command Gen m (Model s)
438 acidQueryCheckFail allow_failure gen_event = Command gen execute
439 [ Require require
440 , Ensure unchanged_model
441 , Ensure correct_output
442 ]
443 where
444 -- Generate queries only when state is open
445 gen model = case modelHandle model of
446 Just st -> Just (AcidCommand <$> gen_event <*> pure st)
447 Nothing -> Nothing
448
449 -- Execute a concrete query directly using acid-state
450 execute (AcidCommand e (Var (Concrete (Opaque st)))) =
451 liftIO (try (evaluate =<< Acid.query st e))
452
453 -- Shrinking queries requires the state to be open
454 require model _ = isOpen model
455
456 -- Queries should not change the value in the model
457 unchanged_model model0 model1 _ _ = modelValue model0 === modelValue model1
458
459 -- Evaluating the query directly on the model value of the old
460 -- state should give the same result
461 correct_output model _ (AcidCommand c _) r = case modelValue model of
462 Just v -> case r of
463 Right o -> evalState (lookupMethod c) v === o
464 Left e -> allow_failure v c e
465 Nothing -> failure
466
467 -- | Extract the underlying method implementation in the pure 'State'
468 -- monad for an acid-state query or update.
469 lookupMethod :: (Core.Method m, Acid.IsAcidic (Core.MethodState m))
470 => m -> State (Core.MethodState m) (Core.MethodResult m)
471 lookupMethod m = Core.lookupHotMethod mmap m
472 where
473 mmap = Core.mkMethodMap (Common.eventsToMethods Common.acidEvents)
474
475
476 -- | Test the sequential property (agreement between model and
477 -- implementation) for an acid-state component, given the interface, a
478 -- generator for initial values of the state, and a list of commands
479 -- built from 'acidQuery' and 'acidUpdate'. Additional commands will
480 -- be added to open and close the state.
481 --
482 -- Note that if the generator for initial values can return more than
483 -- one result, this will fail due to #20.
484 acidStateSequentialProperty :: AcidStateInterface s -> Gen s -> Range Int -> [Command Gen (TestT IO) (Model s)] -> Property
485 acidStateSequentialProperty i gen_initial_state range commands = property $ do
486 actions <- forAll $ Gen.sequential range StateAbsent $
487 [ open i gen_initial_state
488 , close i
489 , checkpoint i
490 , checkpointClose i
491 , kill i
492 ] ++ commands ++ commands
493 test $ do liftIO $ resetState i
494 executeSequential StateAbsent actions
495
496 -- | Test the parallel property (absence of race conditions) for an
497 -- acid-state component, given the interface, a generator for initial
498 -- values of the state, and a list of commands built from 'acidQuery'
499 -- and 'acidUpdate'. Additional commands will be added to open and
500 -- close the state.
501 --
502 -- Note that if the generator for initial values can return more than
503 -- one result, this will fail due to #20.
504 --
505 -- The state cannot be opened twice in parallel, so the length of the
506 -- sequential prefix must be at least 1, so that the open command
507 -- happens exactly once.
508 acidStateParallelProperty :: AcidStateInterface s -> Gen s -> Range Int -> Range Int -> [Command Gen (TestT IO) (Model s)] -> Property
509 acidStateParallelProperty i gen_initial_state prefix_range parallel_range commands = property $ do
510 actions <- forAll $ Gen.parallel prefix_range parallel_range StateAbsent $
511 [ open i gen_initial_state
512 , checkpoint i
513 ] ++ commands ++ commands
514 test $ do liftIO $ resetState i
515 executeParallel StateAbsent actions
516
517 -- | Test that restoring an acid-state component (with the given initial
518 -- value), then executing the given query, results in the given
519 -- expected value. This is mostly useful to test that restoring from
520 -- files created by an older version of acid-state can still be read.
521 restoreOldStateProperty :: (Acid.EventState e ~ s, Acid.EventResult e ~ r, Acid.QueryEvent e, Eq r, Show r)
522 => AcidStateInterface s -> s -> e -> r -> Property
523 restoreOldStateProperty i initial_state q expected_result = withTests 1 $ property $ test $ do
524 liftIO $ removeFile (statePath i ++ "/open.lock") `catch` (\ (_ :: IOException) -> return ())
525 st <- liftIO $ openState i initial_state
526 r <- liftIO $ Acid.query st q
527 r === expected_result