package monolith

Changes

2025/09/22

• The new combinator comparison describes the result of a three-way comparison function, typically a compare function.

2025/03/14

• The new function run can be used to start Monolith's testing engine without allowing Monolith to parse the command line. The function main, which parses the command line and starts testing, can still be used. (Suggested by Gabriel Scherer.)
• If the command line is parsed via main then the command line options --fuel <int> and --max_scenarios <int> and --save-scenario <bool> and --show-scenario <bool> and --timeout <int> are supported.
• In random testing mode, a single counter and clock is now used for all tests, whereas previously a fresh counter and clock would be created every time a smaller value of fuel was adopted. This affects the information messages that are emitted once every second. (Contributed by Gabriel Scherer.)
• The internal error Argh -- reached max environment size, which under infrequent circumstances could appear, has been eliminated.
• Makefile.monolith: change make unattended to use random testing mode instead of AFL mode and to stop after TIMEOUT seconds or MAX failure scenarios have been reached. As a result, Monolith's own make test now runs reliably in about 20 seconds (wall clock time) on a modern machine.

2024/11/26

• The documentation of the specification combinators has been re-organized in sections and subsections. Finding the desired combinator should now be easier.
• The new combinator naive_array offers limited support for arrays.
• The new combinator naive_seq offers limited support for sequences (that is, for the type constructor Seq.t).
• The new combinator pair is a synonym for ( *** ).
• The new combinator triple offers support for triples.
• The new combinator either offers support for the type constructor Either.t.
• The new combinators iter, foldr, foldl, iteri, foldri, foldli offer support for iteration functions.
• An unintentional and undocumented limitation has been fixed: so far, uses of the combinator map_into would work only at the root of the specification or in the right-hand side of an arrow ^>. It should now be possible to use map_into under other combinators that expect a deconstructible specification, such as ^!> (in the right-hand side), ( *** ), option, result, list, etc. This improvement affects not only map_into, but also a number of other combinators that are defined in terms of map_into.
• Monolith now requires OCaml 4.12 or later.

• In Makefile.monolith,

  • the default switch is changed from 4.11.1 to 4.14.2; this can be overridden by defining SWITCH;
  • make test automatically disables the MacOS crash reporter;
  • the use of ulimit -s is abandoned.

2023/06/04

• Fix a bug in Gen.with_source where a file descriptor was not properly closed, causing Monolith to eventually run out of descriptors. (Contributed by Samuel Hym.)
• Fix a minor bug that could cause an assertion failure while printing an error scenario.
• Fix a bug in Makefile.monolith that would cause make test to launch multiple instances of dune in parallel and therefore to fail.
• Remove the use of Obj.magic in module Tag.

2021/05/25

• Fix a bug where the exception PleaseBackOff was unintendedly caught by the combinator ^!> and therefore did not work as intended. (Reported and fixed by Nicolas Osborne.)

2020/10/26

• The functions declare_concrete_type, &&& and &&@ disappear. They are replaced with two new combinators, constructible and deconstructible. The combinator ifpol (described further on) can be used to construct a specification that is both constructible and deconstructible. The idiom int &&& range is replaced with int_within range.
• The function declare_abstract_type no longer requires the type's name as an argument; it takes a unit argument instead.
• The arrow combinator ^^> is renamed ^>. The dependent arrow combinator ^&> is renamed ^>>.
• New specification combinator ^!>. This combinator describes a function that can raise an exception, and requires the reference implementation and the candidate implementation to raise exactly the same exception.
• New specification combinator ^?>. This combinator describes a nondeterministic function. spec1 ^?> spec2 is a short-hand for spec1 ^> nondet spec2.
• New specification combinator ^!?>. This combinator describes a function that can raise an exception, and can decide in a nondeterministic way whether it wishes to raise an exception and what exception it wishes to raise. The reference implementation is allowed to observe this behavior and to react accordingly.
• New specification combinators ^!>>, ^?>>, and ^!?>>. These are the dependent variants of the previous three combinators.
• New specification combinators option, result, and list. These combinators make it easy to describe an operation that expects or returns an option, a result, or a list.
• New specification combinator declare_seq. This (effectful) combinator makes it relatively easy to describe an operation that expects or returns a sequence.
• New specification combinator map_into. This combinator is typically used to wrap an operation or to transform the result of an operation.
• New specification combinator map_outof. This combinator is typically used to construct an argument to an operation via a transformation.
• Removed the combinator map, whose type was fishy.
• New specification combinators rot2 and rot3. (rot2 is also known as flip.) These combinators move a distant argument to the front. This is useful when a dependency between arguments runs contrary to the order of the arguments. These combinators can be used only in a positive position.
• New specification combinators curry and uncurry. These combinators transform a function that expects a pair into a function that expects two separate arguments, and vice-versa. These combinators can be used only in a positive position.
• New specification combinator ignored. This combinator is used to describe the output (or part of the output) of an operation, and indicates that this output should be ignored.
• Changed the type of the specification combinator nondet. Removed the limitation that this combinator can be applied only to a concrete type.
• New specification constant exn. The new function override_exn_eq allows overriding the notion of equality that is associated with the concrete type exn. This is useful when the reference implementation and candidate implementation raise different exceptions.
• New specification combinator ifpol, which allows distinguishing between negative and positive occurrences in a specification. This low-level combinator can be useful in the definition of higher-level abstractions.
• New specification combinator fix, which allows building recursive specifications.
• New specification combinator abstract, which declares an abstract type on the fly, together with a conversion operation out of this abstract type to its concrete definition. This can be used to deal with functions that return functions.
• New exception PleaseBackOff, which the reference implementation is allowed to raise when an operation (or some particular case of an operation) is illegal or is not implemented. This causes the Monolith engine to silently ignore this scenario. No side effects must be performed by the reference implementation before raising this exception.
• New exception Unimplemented, which the candidate implementation is allowed to raise when an operation (or some particular case of an operation) is not implemented. This causes the Monolith engine to silently ignore this scenario.
• New definition of the type 'a code as a synonym for 'a * appearance. New constructors for the type appearance, including constant, document, and infix.
• The functions interval and interval_ are renamed semi_open_interval and closed_interval.
• Significant internal changes, leading to simpler and possibly faster code.
• The file Makefile.monolith is now installed with the library, so it need no longer be copied into one's project, unless one wishes to adapt it.
• In Makefile.monolith, new entries make multicore and make tmux, both of which implement parallel fuzzing with multiple afl-fuzz processes.
• In Makefile.monolith, new entry make random, which implements random testing.
• On 64-bit machines, the function bits did not generate the full range of 63-bit integers; it was inadvertently limited to 32-bit integers. A number of other functions that depend on it, such as interval, were also wrong. Fixed (hopefully).

2020/06/09

• Initial release.