diff --git a/CHANGES.markdown b/CHANGES.markdown new file mode 100644 --- /dev/null +++ b/CHANGES.markdown @@ -0,0 +1,812 @@ +## Changes in 2.11.17 (2026-03-04) + - Compatibility with QuickCheck 2.18 + +## Changes in 2.11.16 (2025-12-12) + - Add support for MicroHs + +## Changes in 2.11.15 (2025-12-08) + - Remove redundant `tf-random` dependency + +## Changes in 2.11.14 (2025-09-30) + - Make sure that `--pretty` completes in *O(n)* time + +## Changes in 2.11.13 (2025-09-15) + - Make diff algorithm line based + - Improve pretty-printing of nested records + +## Changes in 2.11.12 (2025-03-17) + - Add `--no-rerun` and `--no-rerun-all-on-success` + +## Changes in 2.11.11 (2025-02-17) + - Compatibility with GHC 9.12 + +## Changes in 2.11.10 (2024-11-16) + - Add (experimental) extensions API + - Handle small terminal sizes more gracefully when reporting progress + - Correctly indent multi-line pending messages + - Use "erase in line" ANSI sequence to clear transient output (instead of + overwriting it with spaces) + +## Changes in 2.11.9 (2024-05-24) + - Compatibility with GHC 9.10.1 + - Drop support for GHC 7.10.3 + +## Changes in 2.11.8 (2024-04-22) + - Make the build pass with QuickCheck 2.15 + +## Changes in 2.11.7 (2023-10-22) + - Include `--seed` in the note on how to rurun a failing item. + +## Changes in 2.11.6 (2023-10-11) + - Compatibility with GHC 9.8.1 + - Run cleanup actions on `--fail-fast` (see #860) + +## Changes in 2.11.5 (2023-09-20) + - Add `--show-exceptions` and `--display-exceptions` + +## Changes in 2.11.4 (2023-07-20) + - Depend on `hspec-expectations-0.8.4` + +## Changes in 2.11.3 (2023-07-10) + - Suppress informational output from QuickCheck when + `Test.QuickCheck.Args.chatty` is `False` (#840) + +## Changes in 2.11.2 (2023-07-06) + - Add `--expert` mode + +## Changes in 2.11.1 (2023-05-28) + - Depend on `hspec-expectations-0.8.3` + +## Changes in 2.11.0.1 (2023-04-28) + - Don't crash when home directories are unsupported (WASM/WASI) (thanks + @amesgen) + +## Changes in 2.11.0 (2023-04-21) + - Drop support for GHC < 7.10.3 + - Improve coloring of whitespace-only segments on `--diff` + - Add `ColorizedReason` constructor to `FailureReason` + - Provide a new package `hspec-api`, a stable API that can be used to extend + Hspec's functionality. + - Deprecate `Test.Hspec.Core.Formatters.V1` in favor of + `Test.Hspec.Api.Formatters.V1` + - Add `--fail-on=empty-description` + - Print slow spec items to `stderr` instead of `stdout` + - Handle quoting/escaping in `.hspec` files + - Flush output handle after reporting progress on `-fprogress` + +## Changes in 2.10.10 (2023-03-07) + - Re-export `sequential` from `Test.Hspec` + - Rerun `beforeAll` / `afterAll` on `--rerun-all-on-success` (#768) + +## Changes in 2.10.9 (2023-01-13) + - Print error message on `-—fail-on=empty` + - Only fail on `-—fail-on=empty` if at least one spec item has been filtered + - Re-export more types from `Test.Hspec.Core.Runner` + - Fix a pretty-printing bug where `[]` would be pretty-printed as `""` + - Don't pretty-print if the expected and actual value would be equal after + pretty-printing + - Prevent deadlocks on unguarded exceptions in runner (#771) + +## Changes in 2.10.8 (2022-12-19) + - Add pretty-printing support for rational numbers + - Force / evaluate exceptions recursively (#763) + - Add `xprop` and `fprop`, which use `xit` and `fit` (thanks @lehins) + +## Changes in 2.10.7 (2022-12-03) + - Do not depend on `ghc` for pretty-printing (#750, #752) + +## Changes in 2.10.6 (2022-09-13) + - Suppress excessive diff output (#449) + - Allow the use of an external diff program. This can e.g. be used by + setting `HSPEC_DIFF_COMMAND="diff -u --color -L expected -L actual"` or + `HSPEC_DIFF_COMMAND="git diff"` + - Do not imply `--fail-on=empty` on `--strict` + +## Changes in 2.10.5 (2022-09-09) + - Add `--fail-on`. This subsums `--fail-on-focused` and `--fail-on-pending`. + - Add `--fail-on=empty` (#650) + - Add `registerFormatter` and `registerDefaultFormatter` to + `Test.Hspec.Runner`. + - Revert deprecation of `Test.Hspec.Formatters` and + `Test.Hspec.Core.Formatters`. Instead the module documentation now says + that they are deprecated in favor of `Test.Hspec.Core.Formatters.V1`. + +## Changes in 2.10.4 (2022-09-06) + - Make sure that whitespace-only diff output is colorized properly (#660) + +## Changes in 2.10.3 (2022-09-05) + - Deprecate `Test.Hspec.Formatters` and `Test.Hspec.Core.Formatters` + - Disable (most) warnings in files generated by `hspec-discover` (#702) + +## Changes in 2.10.2 (2022-09-03) + - Add `--strict` + - Add `--fail-on-pending` + - Do not depend on `clock` + +## Changes in 2.10.1 (2022-08-22) + - Support for GHC 9.4.1 + - Generated modules now include an export list + +## Changes in 2.10.0.1 (2022-08-06) + - Fix a deadlock with nested failed `aroundAll`s (see #679) + +## Changes in 2.10.0 (2022-05-12) + - Allow to transform the config in `SpecM` + - Allow to customize pretty-printing (via `configPrettyPrintFunction`) + - Add `getSpecDescriptionPath` (#637, thanks @srid) + - Do not treat `afterAll` as another spec item (fixes #414, #364, #363) + - Change type of `paramsSmallCheckDepth` to Maybe (see #345) + +## Changes in 2.9.7 + - Ensure that interim output does not interfere with output from tests This + facilitates using `print` when debugging test cases. + +## Changes in 2.9.6 + - Ensure color codes don't span newlines (#346, thanks @robx) + - Disable progress reporting on Buildkite + - Improve error messages on exceptions in hooks + +## Changes in 2.9.5 + - Assume `--color` by default when running on GitHub Actions. Use + `HSPEC_COLOR=no` or `--no-color` to opt out of this behavior. + - Disable progress reporting on GitHub Actions. + - Retain source formatting of numbers when pretty-printing. + +## Changes in 2.9.4 + - Compatibility with GHCJS (see #599) + +## Changes in 2.9.3 + - Pretty-print Haskell values in failure messages + +## Changes in 2.9.2 + - Show multi-line diffs for string literals (disable with `--no-pretty`) + +## Changes in 2.9.1 + - Recover unicode from `ExpectedButGot` + - Preserve unicode in `To rerun use: --match ...` output + +## Changes in 2.9.0 + - Add ASCII fallbacks to "checks" formatter (fixes #512) + - Use `checks` formatter by default (to restore the old behavior use + `--format specdoc`) + - Allow to extend the list of available formatters for `--format` + (`configAvailableFormatters`) + - Add `getExpectedTotalCount` to `Test.Hspec.Core.Formatters.V2` + - Rename `formatConfigItemCount` to `formatConfigExpectedTotalCount` + - Rename `configFastFail` to `configFailFast` + +## Changes in 2.8.5 + - hspec-core: Include help.txt in package tarball (close #568) + - hspec-discover: Require base >=4.5.0.0 (fixes #554) + +## Changes in 2.8.4 + - Better support for GHC 9.2.1 + - Support for setting options by individual environment variables, e.g. + `HSPEC_COLOR=yes` will set `--color` + +## Changes in 2.8.3 + - Better support for `--color=auto` on Windows + - Add support for spec hooks to `hspec-discover` (via `SpecHook.hs`) + - Propagate exceptions from `Test.Hspec.Core.Format.monadic` + - Re-export `aroundAll_` from `Test.Hspec` + +## Changes in 2.8.2 + - Add `mapSubject` and `ignoreSubject` + +## Changes in 2.8.1 + - Take the environment variable `NO_COLOR` into account + +## Changes in 2.8.0 + - Add `--times` to print times for individual spec items + - Add `--print-slow-items` + - Use `-XNoImplicitPrelude` and do not rely on `base` for `hspec-discover` + generated test drivers. This ensures full compatibility with custom + preludes. + - Add new APIs for formatters `Test.Hspec.Core.Format` and + `Test.Hspec.Core.Formatters.V2` + - Add `getItemCount` to `Formatter` API + - Add `--qc-max-shrinks` (see #380) + - Add location information for failing `afterAll`-hooks + - hspec-discover: Deprecate `--no-main` and `--formatter` (use + `--module-name` instead) (#196) + - Remove `--verbose` option (this has been a noop since at least 2013) + - Remove `--out` option (use shell output redirection instead) + +## Changes in 2.7.10 + - Add a new formatter (can be used with `--format checks`) + - Add `exampleStarted` to `Formatter` API + +## Changes in 2.7.9 + - Re-export `aroundAll` and `aroundAllWith` from `Test.Hspec` + +## Changes in 2.7.8 + - Add `aroundAll` / `aroundAllWith` (see #255) + +## Changes in 2.7.7 + - Add `aroundAll_` (see #255) + - Correctly handle pending for `afterAll` actions + +## Changes in 2.7.6 + - Add `beforeAllWith` (see #447) + +## Changes in 2.7.5 + - Extract source locations from `NoMethodError` and `AssertionFailed` + +## Changes in 2.7.4 + - Apply `--randomize` recursively + +## Changes in 2.7.3 + - Add `--randomize` + +## Changes in 2.7.2 + - Interrupt diff calculation if it takes longer than two seconds (see #415) + +## Changes in 2.7.1 + - Add compatibility with QuickCheck 2.13.1 (see #410) + +## Changes in 2.7.0 + - Add `--focused-only` (see #390) + - Add `--fail-on-focused` (see #389) + +## Changes in 2.6.1 + - Add `Test.Hspec.Runner.runSpec` (see #216) + +## Changes in 2.6.0 + - Allow to focus individual spec items (see #319) + - Do not calculate diff on `--no-diff` (see #332) + - Remove deprecated module Test.Hspec.Core + +## Changes in 2.5.9 + - Extract source locations from RecConError (see #375) + +## Changes in 2.5.8 + - Add `modifyArgs` and `modifyMaxShrinks` to `Test.Hspec.QuickCheck` (see #380) + +## Changes in 2.5.7 + - GHC 8.6.1 related changes + +## Changes in 2.5.6 + - Compatibility with `QuickCheck-2.12` + +## Changes in 2.5.5 + - Use `module[line:column]` instead of `module:line:column` as default label + for `describe`/`it` (fixes #366) + +## Changes in 2.5.4 + - Show how to rerun individual spec items on test failures (see #205) + +## Changes in 2.5.3 + - Treat character escapes like `\NUL` as single tokens on `--diff` (see #351) + - Allow a `/` at the beginning and at the end of an absolute path that is + passed to `--match` or `--skip` + +## Changes in 2.5.2 + - Use module:line:column as default label for describe/it (see #250) + - Warn if user is affected by https://ghc.haskell.org/trac/ghc/ticket/13285 (see #329) + +## Changes in 2.5.1 + - Disable tests for Test.Hspec.Core.Timer (see #352) + +## Changes in 2.5.0 + - Add `sequential` (see #311) + - Add support for `--diff` when `shouldBe` is uesd with + `QuickCheck`-properties + - Add source locations when `shouldBe` is uesd with `QuickCheck` properties + - Print `QuickCheck` labels on success (see #297) + - Retain output of `verbose`, `label`, `collect`, `classify`, etc. for + `QuickCheck` properties (see #257) + - Extract source location from error / undefined (see #316) + - Parse source locations from pattern match failures + - Include source column when formatting source locations + - Colorize whitespaces with background color instead of foreground color with + `--diff` + - Run `Test.Hspec.Core.Formatters.exampleProgress` in `FormatM` instead of + `IO` + - Make sure that progress output is always cleared (fixes #301) + - Add location information to `pending` (not used by any formatter yet) + - Include duration for each spec item in new formatter API (see #315) (not yet exposed) + - Removed deprecated module `Test.Hspec.HUnit`, use + `Test.Hspec.Contrib.HUnit` instead + - Deprecate `--out` + - Remove `BestEffort` source locations + +## Changes in 2.4.8 + - compatibility with GHC 8.4.1-alpha3 + +## Changes in 2.4.7 + - compatibility with `QuickCheck-2.11.3` and up (note that `QuickCheck` + versions `2.11` to `2.11.2` are not fully supported) + +## Changes in 2.4.6 + - compatibility with the upcoming version `4.11.0.0` of `base` + +## Changes in 2.4.5 + - `hspec-discover`: Sort specs using natural sort order + +## Changes in 2.4.4 + - Require quickcheck-io >= 0.2.0 + +## Changes in 2.4.3 + - Read command-line options from environment variable `HSPEC_OPTIONS` + +## Changes in 2.4.2 + - Use `--diff` by default + - Add `--failure-report` (see #266) + +## Changes in 2.4.1 + - Compatibility with HUnit < 1.3 + +## Changes in 2.4.0 + - Read command-line options from config files `~/.hspec` and `.hspec` + - Add support for `--diff` + - Add `xit`, `xspecify`, `xdescribe` and `xcontext` (see #252) + - Add `--rerun-all-on-success` + - Report exceptions in `beforeAll` operations only once + - Add indentation when actual/expected contain newlines (see #263) + - More graceful shutdown on ctrl-c (see #270) + - Run around-hook for Bool and Result (see #252) + - Include `CHANGES.markdown` in package tarball + +Internal changes: + + - Rename `Fail` constructor of `Result`-type to `Failure` + - Add `FailureReason` type + - Add `Test.Hspec.Core.Spec.safeEvaluateExample` + +## Changes in 2.3.2 + - Compatibility with HUnit 1.5 + +## Changes in 2.3.1 + - Fix build for HUnit < 1.4 + +## Changes in 2.3.0 + - Proper support for GHC 8 call stacks + +## Changes in 2.2.4 + - Compatibility with QuickCheck-2.9 + +## Changes in 2.2.3 + - Make sure that `cabal haddock` works for `hspec-discover` + - Forward compatibility for HUnit 1.4 + - Fix tests for GHC 8.0.1-rc1 + +## Changes in 2.2.2 + - Fix compilation for GHC 8.0.1-rc1 + +## Changes in 2.2.1 + - Make sure that Vim's default `errorformat` recognizes exact locations + - GHCJS compatibility + +## Changes in 2.2.0 + - Add source locations to test `Result` + +## Changes in 2.1.10 + - GHC 7.0.* compatibility + +## Changes in 2.1.9 + - Make use of GHC 7.10.2 source locations + - Add `--jobs` + +## Changes in 2.1.8 + - Depend on `hspec-expectations-0.7.0" + +## Changes in 2.1.7 + - Add `beforeAll_` + +## Changes in 2.1.6 + - If there were no previous failures, run all spec items on `--rerun` + +## Changes in 2.1.5 + - Compatibility with QuickCheck-2.8 + +## Changes in 2.1.4 + - Make `hspec-discover` ignore modules with invalid module names, this fixes + issues with `flycheck`'s temporary files + +## Changes in 2.1.3 + - Format source locations like gcc does + +## Changes in 2.1.2 + - Re-export `before_` from `Test.Hspec` + +## Changes in 2.1.1 + - Add `before_` + - Add command-line option `--skip` + +## Changes in 2.1.0 + - Generalize `after_`, `afterAll_` and `around_` + +## Changes in 2.0.2 + - Indent error messages for failed examples (fixes #186) + - Export `defaultParams` from `Test.Hspec.Core.Example` + - Bring back `Test.Hspec.HUnit` and deprecate it to provide a smother upgrade + path + +## Changes in 2.0.1 + - Add missing extra source files to for `hspec-discover` + +## Changes in 2.0.0 + - Split package into `hspec`, `hspec-core` and `hspec-discover` + - Allow hooks (`before`, `around`, etc.) to pass arguments to spec items + - Do not print `-` in front of spec items with `specdoc` formatter + - Move `Test.Hspec.HUnit` to `hspec-contrib` + +## Changes in 1.12.4 + - Add `specGroup` and `specItem` to `Test.Hspec.Core` + - Deprecate `Test.Hspec.Core.it` and `Test.Hspec.Core.describe` + +## Changes in 1.12.3 + - Make `hspec-discover` work with `-XNoImplicitPrelude` + +## Changes in 1.12.2 + - Include `IOErrorType` when printing uncaught `IOException`s (see #204) + +## Changes in 1.12.1 + - Add `--module-name` option to `hspec-discover` (see #168) + +## Changes in 1.12.0 + - Add optional source location to spec items + - Move item requirement text from `SpecItem` constructor to `Item` data type + - Remove `BuildSpecs` constructor from `SpecTree`, having `runIO` this is not + really needed + - Add `mapSpecTree` to `Test.Hspec.Core` + - Add `afterAll` (see #188) + - Do not return `Result` from `hspecWith` and accept command-line options + (the old behavior is still available as `hspecWithResult`) + - Rename `configHandle` to `configOutputFile` + - Omit empty `describe` groups from report + - Do not pass position to `Formatter.exampleGroupStarted` (we can not support + this with the upcomming cleanup actions #188) + - Do not print empty lines before/after spec groups + - Deprecate `Test.Hspec.Formatters.newParagraph` + +## Changes in 1.11.4 + - Make test suite independent from QuickCheck seed (see #187) + +## Changes in 1.11.3 + - Depend on `hspec-expectations-0.6.1` + +## Changes in 1.11.2 + - Add `beforeAll` + +## Changes in 1.11.1 + - Add `specify` as an alias for `it` + +## Changes in 1.11.0 + - Add `BuildSpecs` constructor to internal `SpecTree` data structure. This + allows you to do `IO` while constructing the spec tree. + - Add `runIO` + +## Changes in 1.10.0 + - Do not use exception type to distinguish between synchronous/asynchronous + exceptions (thanks to Michael Snoyman) + - Remove `Example` instance for `Test.HUnit.Test` (#101), use + `Test.Hspec.HUnit.fromHUnitTest` instead. + - Do not reexport `property` from `Test.Hspec.QuickCheck` + - Move `ProgressCallback` out of `Params` + - Add show instance for `Params` + - Move requirement text from `Item` to `SpecItem` constructor + - Remove deprecated modules and functions + +## Changes in 1.9.5 + - Make sure that ctrl-c works properly with GHC 7.8.* and QuickCheck-2.6 + +## Changes in 1.9.4 + - Compatibility with transformers-0.4.0.0 + +## Changes in 1.9.3 + - Make internal Tree data structure more strict (#169) + +## Changes in 1.9.2 + - Print type of exceptions that are raised from QuickCheck properties (#94) + +## Changes in 1.9.1 + - Bring back compatibility with older versions of QuickCheck (#166) + +## Changes in 1.9.0 + - Depend on QuickCheck 2.7 + +## Changes in 1.8.3 + - Do not use color if `TERM=dumb` (see #158) + +## Changes in 1.8.2 + - `hspec-discover` now accepts `--no-main` which results in a top-level spec + being generated instead of a test driver (thanks @DanielG) + - Make sure that `after` is run on failing tests (see #159) + +## Changes in 1.8.1 + - Add `shouldMatchList` + +## Changes in 1.8.0 + - Run `before`/`after`/`around` for each single check of a QuickCheck property + - Add `Test.Hspec.Core.mapSpecItem` + - Add `modifyMaxSuccess`, `modifyMaxDiscardRatio` and `modifyMaxSize` to + `Test.Hspec.QuickCheck` + - Don't fail if callback is not called in `around` + - `hspec-discover`: Remove `--nested` option + - `hspec-discover`: Ignore `Spec.hs`/`Spec.lhs` + +## Changes in 1.7.2 + - Add `after` and `around` + +## Changes in 1.7.1 + - Add `shouldContain` (thanks to Alfredo Di Napoli) + - When printing progress, skip total if it is 0 + - Do not colorize the description/requirement in failure list + +## Changes in 1.7.0 + - Add `--depth` for use with `hspec-smallcheck` + +## Change in 1.6.2 + - Add `before` + - Add `--qc-max-discard` and `--qc-max-size` + +## Changes in 1.6.1 + - Allow to specify the output file with `--out` + +## Changes in 1.6.0 + - Add support for parallelization + - Change license to MIT + - Add MonadIO instance for FormatM + - Add support for custom formatters to hspec-discover + - Add hspecResult + - Rename `--re-run` to `--rerun` + add documentation (#95) + - Remove `configVerbose` + - Use same `--qc-max-success` on `--rerun` (#125) + - Add command-line option `--no-color`, `--color` does not accept arguments + anymore (#130) + +## Changes in 1.5.4 + - Make sure that QuickCheck is never chatty + - Make sure progress for QuickCheck examples is shown + +## Changes in 1.5.3 + - Print "Randomized with seed ..." only once + +## Changes in 1.5.2 + - Add `--seed`, it can be used to specify the seed for QuickCheck properties + - Reuse previous seed on `--re-run` + +## Changes in 1.5.1 + - Depend on quickcheck-io + +## Changes in 1.5.0 + - Allow to use expectations as QuickCheck properties (#80) + - Do not suppress output to `stdout` + - Change type of `pending` to `Expectation`, add `pendingWith` (#121) + - Add the `example` function, it fixes the type of an Expectation (#86) + - Rename `--fast-fail` to `--fail-fast` (for consistency with RSpec) + - Do not clutter Cabal test suite logs with QuickCheck output (#112) + - Skip redundant output from QuickCheck failure messages (#102) + +## Changes in 1.4.5 + - hspec-discover now discovers .lhs files, too + +## Changes in 1.4.4 + - Visually distinguish error message from requirements in the summary (#100) + - Export `formatException` from `Test.Hspec.Formatters` + - Add `--fast-fail` (#82) + - Print a summary on UserInterrupt/ctrl-c (#107) + +## Changes in 1.4.3 + - Add `--dry-run` (#111) + +## Changes in 1.4.2 + - Properly handle ctrl-c while running QuickCheck properties (#93) + - Default to `--color=always` when `--color` is used without argument (#106) + - treat `--qc-max-success` as an alias for `--maximum-generated-tests` + +## Changes in 1.4.1 + - Used CPU time is now only included in the test summary if run with + `--print-cpu-time`. + +## Changes in 1.4.0 + - We now have a manual at https://hspec.github.io/. The sources are in + `doc/`. It's still work in progress. Contributions are very welcome! + - The Haddock documentation now indicates the stability of each exposed + module. `Test.Hspec` is now considered stable. + - `hspec` now supports command-line options + - `--color` can be used to enable/disable colored output + - `--format` can be used to pick a specific formatter + - `--html` can be used to produce an HTML report + - `--maximum-generated-tests` can be used to specify QuickCheck's + `maxSuccess` + - `--match` only runs spec items that match a given string + - `--re-run` only runs spec items that previously failed. This is + undocumented, + experimental and only works within GHCi (use `:reload` / `:main`)! + - Runner functions exported from `Test.Hspec.Runner` new expect a monadic + spec. + - `fromHUnitTest` has been added. It can be used to run existing HUnit test + suites with Hspec. + - The `Example` instance for HUnit `Test`s has been deprecated. + `fromHUnitTest` can be used instead. The primary motivation is, that + `fromHUnitTest` gives more detailed reporting for nested HUnit test suites. + - `Test.Hspec.Monadic` has been deprecated, all functionality is available + through one of `Test.Hspec`, `Test.Hspec.Core` or `Test.Hspec.Runner`. + - More of Hspec's internals are now exposed from `Test.Hspec.Core` + - All runner functions for the core spec type (aka as non-monadic spec) have + been deprecated, use e.g. `Test.Hspec.hspec . fromSpecList` instead. The + motivation is to provide an API that does not expose colliding names. + - Some other stuff from `Test.Hspec.Core` that collides with other parts of + the API has been deprecated. Compatible alternatives are given in each + deprecation message. + - The default formatter now produces less whitespace (#73) + other minor + improvements + - The formatter API has been revamped. + - The exception type is now printed if an example fails due to an exception + (#50) + - The number of pending examples is now printed after each test run (#85) + - `--verbose` has been added (#87) + +## Changes in 1.3.0 + + - `Test.Hspec` now re-exports the monadic API. If you still use the + non-monadic API, you can use `Test.Hspec.Core` as a drop-in replacement. + + - `hspec-expectations`, a set of combinators that allow to express + expectations about the outcome of code examples, is now included with Hspec. + Have a look at the [README of `hspec-expectations`] + (https://github.com/sol/hspec-expectations#readme) + for a short introduction. + + - `hspec-discover`, a mechanism for automatic spec discovery, is now an + official part of Hspec. + Have a look at [`hspec-discover`'s README] + (https://github.com/hspec/hspec/tree/main/hspec-discover#readme) + for a short introduction. + +## Changes in 1.2.0 + + - `hspec` has been removed, and `hspecX` has been renamed to `hspec` (see + [#71](https://github.com/hspec/hspec/issues/71)) + + - `hHspec` now returns a summary of the test run. + + - The time reporting after a test run is not colored anymore. + +## Changes in 1.1.3 + + - `Test.Hspec` warns now about future changes: It will re-export + `Test.Hspec.Monadic` in the future. If you still use the non-monadic API, + you can either use `Test.Hspec.Core` as a drop-in replacement, or migrate your + code to the monadic API. + + The monadic API is more stable and easier to use. Now is a good time to + switch! + + - `Test.Hspec.Core` is now a proper superset of `Test.Hspec` + +## Changes in 1.1.2 + + * All descriptions of nested examples are now included in summary for failing + examples + + * `context` is now an alias for `describe` + +## Changes in 1.1.1 + + * Specs from Test.Hspec.Monadic has been renamed to Spec. For backward + compatibility Specs is still kept as an alias. + +## Changes in 1.1.0 + +### The reason for pending examples is now optional + +With this change, both of the following code snippets work. + +```haskell +it "some behavior" $ + pending -- no reason given +``` + +```haskell +it "some other behavior" $ + pending "some reason" +``` + +### Hspec does not rely on ExistentialQuantification anymore + +### The type used to represent specs is now abstract + +This should give more useful error messages when adapting old specs that use +the non-monadic API for `hspec-1.0`/`hspec-1.1`. + +### Several internal types and functions have been deprecated + +Those are internal functions, and they will be removed/hidden with the next +release. If you use any of those, update your code. If you really need them, +[open a ticket](https://github.com/hspec/hspec/issues) and describe your use +case. + +## Changes in 1.0.0 + +### Hspec now re-uses QuickCheck's property function + +`Test.Hspec.QuickCheck.property` is now simply a re-exports of +`Test.QuickCheck.property`. This has the advantage that you do not get a name +collision if you import both, `Test.Hspec.QuickCheck` and `Test.QuickCheck`. + +### Better support for nested specs + +*NOTE: This is a breaking change to the non-monadic API. The monadic API is +not affected.* + +In some situations parent descriptions for nested specs were not included in +the generated report. Solving this required a change to the data structure +that is used to represent specs (it was not a proper tree, now it is). + +#### Updating specs that use the non-monadic API + +The runner functions (`hspec`, `hspecB` and `hspecX`) now take a list of +descriptions. + +The following works with `hspec-0.9`, but not with `hspec-1.0`. + +```haskell +main = hspecX $ + describe "reverse" [ + it "reverses a list" $ + reverse [1, 2, 3] == [3, 2, 1], + + it "gives the original list, if applied twice" $ property $ + \xs -> reverse (reverse xs) == (xs :: [Int]) + ] + +``` + +For `hspec-1.0`, you need to wrap it into a list. + +```haskell +main = hspecX [ + describe "reverse" [ + it "reverses a list" $ + reverse [1, 2, 3] == [3, 2, 1], + + it "gives the original list, if applied twice" $ property $ + \xs -> reverse (reverse xs) == (xs :: [Int]) + ] + ] +``` + +Specs consisting of several *describes*, combined with `descriptions`, continue +to work unchanged. But `descriptions` is now a noop, and it will be removed in +a future release. So it is a good idea to drop it. + +The following works with both `hspec-0.9` and `hspec-1.0`. + +```haskell +main = hspecX $ descriptions [ -- descriptions is redundant + describe "Foo" [ + it "has some behavior" True + ] + , describe "Bar" [ + it "has some behavior" True + ] + ] +``` + +But the following is recommended instead. + +```haskell +main = hspecX [ + describe "Foo" [ + it "has some behavior" True + ] + , describe "Bar" [ + it "has some behavior" True + ] + ] +``` + +### A new monadic API for custom Formatters + +For all the details, have a look at the [docs] +(https://hackage.haskell.org/packages/archive/hspec/latest/doc/html/Test-Hspec-Formatters.html). + + +### The total time required to run a spec is now included in the summary + +In addition to the used CPU time, the total time required to run a spec is now +include in the summary. This is useful for specs that do non-CPU-intensive +stuff, or fork subprocesses. diff --git a/LICENSE b/LICENSE --- a/LICENSE +++ b/LICENSE @@ -1,10 +1,21 @@ - -Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: - +Copyright (c) 2011-2026 Simon Hengel +Copyright (c) 2011-2012 Trystan Spangler +Copyright (c) 2011-2011 Greg Weber -Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. -Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. -The name of the author may not be used to endorse or promote products derived from this software without specific prior written permission. +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: -THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. diff --git a/Setup.lhs b/Setup.lhs --- a/Setup.lhs +++ b/Setup.lhs @@ -1,14 +1,3 @@ -#!/usr/bin/runhaskell -> module Main where +#!/usr/bin/env runhaskell > import Distribution.Simple -> import Distribution.PackageDescription(PackageDescription) -> import Distribution.Simple.LocalBuildInfo(LocalBuildInfo) -> import System.Cmd(system) -> import Distribution.Simple.LocalBuildInfo -> -> main :: IO () -> main = defaultMainWithHooks hooks -> where hooks = simpleUserHooks { runTests = runspecs } -> -> runspecs :: Args -> Bool -> PackageDescription -> LocalBuildInfo -> IO () -> runspecs _ _ _ lbi = system "runhaskell ./Specs.hs" >> return () +> main = defaultMain diff --git a/Specs.hs b/Specs.hs deleted file mode 100644 --- a/Specs.hs +++ /dev/null @@ -1,214 +0,0 @@ - -module Specs where - -import Test.Hspec.Internal -import Test.Hspec.QuickCheck -import Test.Hspec.HUnit () -import System.IO -import System.Environment -import System.Exit -import qualified Test.HUnit as HUnit - -main :: IO () -main = do - ar <- getArgs - b <- case ar of - ["README"] -> withFile "README" WriteMode (\ h -> hPutStrLn h preable >> hHspec h specs) - [filename] -> withFile filename WriteMode (\ h -> hHspec h specs) - _ -> hspecB specs - exitWith $ toExitCode b - -preable :: String -preable = unlines [ - "hspec aims to be a simple, extendable, and useful tool for Behavior Driven Development in Haskell.", "", - "", - "Step 1, write descriptions and examples of your desired behavior", - "> specs = describe \"myabs\" [", - "> it \"returns the original number when given a positive input\"", - "> (myabs 1 == 1),", - "> ", - "> it \"returns a positive number when given a negative input\"", - "> (myabs (-1) == 1),", - "> ", - "> it \"returns zero when given zero\"", - "> (myabs 0 == 0)", - "> ]", - "", - "Step 2, write whatever you are describing", - "> myabs n = undefined", - "", - "Step 3, watch your examples fail", - "> hspec specs", - "myabs", - " x returns the original number when given a positive input [1]", - " x returns a positive number when given a negative input [2]", - " x returns zero when given zero [3]", - "", - "1) myabs returns the original number when given a positive input FAILED", - "Prelude.undefined", - "", - "2) myabs returns a positive number when given a negative input FAILED", - "Prelude.undefined", - "", - "3) myabs returns zero when given zero FAILED", - "Prelude.undefined", - "", - "Finished in 0.0002 seconds", - "", - "3 examples, 3 failures", - "", - "Step 4, implement your desired behavior", - "> myabs n = if n < 0 then negate n else n", - "", - "Step 5, watch your examples pass", - "> hspec specs", - "myabs", - " - returns the original number when given a positive input", - " - returns a positive number when given a negative input", - " - returns zero when given zero", - "", - "Finished in 0.0000 seconds", - "", - "3 examples, 0 failures", - "", - "", - "", - "", - "Here's the report of hspec's behavior:" ] - -specs :: IO [Spec] -specs = do - exampleSpecs <- describe "Example" [ - it "pass" (Success), - it "fail 1" (Fail "fail message"), - it "pending" (Pending "pending message"), - it "fail 2" (HUnit.assertEqual "assertEqual test" 1 (2::Int)), - it "exceptions" (undefined :: Bool), - it "quickcheck" (property $ \ i -> i == (i+1::Integer))] - - let report = pureHspec exampleSpecs - - -- uncomment the next line to aid in debugging - --mapM_ putStrLn $ ["-- START example specs --"] ++ report ++ ["-- END example specs --"] - - -- the real specs - descriptions [ - - describe "the \"describe\" function" [ - it "takes a description of what the behavior is for" - ((=="Example") . name . head $ exampleSpecs), - - it "groups behaviors for what's being described" - (all ((=="Example").name) exampleSpecs) - ], - describe "the \"it\" function" [ - it "takes a description of a desired behavior" - (requirement (Spec "Example" "whatever" Success) == "whatever" ), - - it "takes an example of that behavior" - (result (Spec "Example" "whatever" Success) == Success), - - it "can use a Bool, HUnit Test, QuickCheck property, or \"pending\" as an example" - (True), - - it "will treat exceptions as failures" - (any (==" x exceptions [3]") report) - ], - describe "the \"hspec\" function" [ - it "displays a header for each thing being described" - (any (=="Example") report), - - it "displays one row for each behavior" - (HUnit.assertEqual "" 29 (length report)), - -- 19 = group header + behaviors + blank lines + time + error messsages + pending message + example/failures footer - - it "displays a '-' for successfull examples" - (any (==" - pass") report), - - it "displays an 'x' for failed examples" - (any (==" x fail 1 [1]") report), - - it "displays a list of failed examples" - (any (=="1) Example fail 1 FAILED") report), - - it "displays available details for failed examples" - (any (=="fail message") report), - - it "displays a '-' for pending examples" - (any (==" - pending") report ), - - it "displays a '#' and an additional message for pending examples" - (any (==" # pending message") report ), - - it "summarizes the time it takes to finish" - (any (=="Finished in 0.0000 seconds") (pureHspec exampleSpecs)), - - it "summarizes the number of examples and failures" - (any (=="6 examples, 4 failures") (pureHspec exampleSpecs)), - - it "outputs to stdout" - (True) - ], - describe "Bool as an example" [ - it "is just an expression that evaluates to a Bool" - (True) - ], - describe "HUnit TestCase as an example" [ - it "is specified with the HUnit \"TestCase\" data constructor" - (HUnit.TestCase $ HUnit.assertBool "example" True), - - it "is the assumed example for IO() actions" - (HUnit.assertBool "example" True), - - it "will show the failed assertion text if available (e.g. assertBool)" - (HUnit.TestCase $ do - innerSpecs <- describe "" [ it "" (HUnit.assertBool "trivial" False)] - let innerReport = pureHspec innerSpecs - HUnit.assertBool "should find assertion text" $ any (=="trivial") innerReport), - - it "will show the failed assertion expected and actual values if available (e.g. assertEqual)" - (HUnit.TestCase $ do - innerSpecs <- describe "" [ it "" (HUnit.assertEqual "trivial" (1::Int) 2)] - let innerReport = pureHspec innerSpecs - HUnit.assertBool "should find assertion text" $ any (=="trivial") innerReport - HUnit.assertBool "should find 'expected: 1'" $ any (=="expected: 1") innerReport - HUnit.assertBool "should find ' but got: 2'" $ any (==" but got: 2") innerReport) - ], - describe "QuickCheck property as an example" [ - it "is specified with the \"property\" function" - (property $ \ b -> b || True), - - it "will show what falsified it" - (any (=="0") report) - ], - describe "pending as an example" [ - it "is specified with the \"pending\" function and an explanation" - (pending "message" == Pending "message"), - - it "accepts a message to display in the report" - (any (== " # pending message") report) - ], - describe "hspecB" [ - it "returns true if no examples failed" - (HUnit.TestCase $ do - ss <- describe "" [it "" Success] - HUnit.assertEqual "no errors" True (snd $ pureHspecB ss)), - - it "returns false if any examples failed" - (HUnit.TestCase $ do - ss <- describe "" [it "" (Fail "test")] - HUnit.assertEqual "one error" False (snd $ pureHspecB ss)) - ], - describe "quantify (an internal function)" [ - it "returns an amount and a word given an amount and word" - (quantify (1::Int) "thing" == "1 thing"), - - it "returns a singular word given the number 1" - (quantify (1::Int) "thing" == "1 thing"), - - it "returns a plural word given a number greater than 1" - (quantify (2::Int) "thing" == "2 things"), - - it "returns a plural word given the number 0" - (quantify (0::Int) "thing" == "0 things") - ]] diff --git a/hspec.cabal b/hspec.cabal --- a/hspec.cabal +++ b/hspec.cabal @@ -1,51 +1,62 @@ -name: hspec -version: 0.3.0 -cabal-version: -any -build-type: Custom -license: BSD3 -license-file: LICENSE -copyright: (c) 2011 Trystan Spangler -maintainer: trystan.s@comcast.net -build-depends: HUnit >=1 && <=2, QuickCheck >=2.4.0.1 && <=2.5, - base >=4 && <=5 -stability: experimental -homepage: https://github.com/trystan/hspec -package-url: https://github.com/trystan/hspec -bug-reports: mailto:trystan.s@comcast.net -synopsis: Behavior Driven Development for Haskell -description: Behavior Driven Development for Haskell - . - Hspec is based on the Ruby library RSpec - so much of what applies to RSpec also applies to Hspec. Hspec ties together /descriptions/ of behavior and /examples/ of that behavior. The examples can then be run as tests and the output summarises what needs to be implemented. -category: Testing -author: Trystan Spangler -tested-with: -data-files: -data-dir: "" -extra-source-files: ./Specs.hs ./src/Test/Hspec/HUnit.hs - ./src/Test/Hspec/Internal.hs ./src/Test/Hspec/QuickCheck.hs -extra-tmp-files: -exposed-modules: Test.Hspec Test.Hspec.HUnit Test.Hspec.Internal - Test.Hspec.QuickCheck -exposed: True -buildable: True -build-tools: -cpp-options: -cc-options: -ld-options: -pkgconfig-depends: -frameworks: -c-sources: -extensions: FlexibleInstances -extra-libraries: -extra-lib-dirs: -includes: -install-includes: -include-dirs: -hs-source-dirs: . src -other-modules: Specs -ghc-prof-options: -ghc-shared-options: -ghc-options: -Wall -hugs-options: -nhc98-options: -jhc-options: +cabal-version: 1.12 + +-- This file has been generated from package.yaml by hpack version 0.39.1. +-- +-- see: https://github.com/sol/hpack + +name: hspec +version: 2.11.17 +license: MIT +license-file: LICENSE +copyright: (c) 2011-2026 Simon Hengel, + (c) 2011-2012 Trystan Spangler, + (c) 2011 Greg Weber +maintainer: Simon Hengel +build-type: Simple +category: Testing +stability: experimental +bug-reports: https://github.com/hspec/hspec/issues +author: Simon Hengel +homepage: https://hspec.github.io/ +synopsis: A Testing Framework for Haskell +description: Hspec is a testing framework for Haskell. Some of Hspec's distinctive + features are: + . + * a friendly DSL for defining tests + . + * integration with QuickCheck, SmallCheck, and HUnit + . + * parallel test execution + . + * automatic discovery of test files + . + The Hspec Manual is at . +extra-source-files: + version.yaml + CHANGES.markdown + +source-repository head + type: git + location: https://github.com/hspec/hspec + +library + ghc-options: -Wall + hs-source-dirs: + src + build-depends: + QuickCheck >=2.12 + , base ==4.* + , hspec-core ==2.11.17 + , hspec-discover ==2.11.17 + , hspec-expectations ==0.8.4.* + exposed-modules: + Test.Hspec + Test.Hspec.Discover + Test.Hspec.Formatters + Test.Hspec.QuickCheck + Test.Hspec.Runner + other-modules: + Paths_hspec + default-language: Haskell2010 + if impl(ghc) + cpp-options: -DENABLE_SPEC_HOOK_ARGS diff --git a/src/Test/Hspec.hs b/src/Test/Hspec.hs --- a/src/Test/Hspec.hs +++ b/src/Test/Hspec.hs @@ -1,83 +1,96 @@ - --- | Hspec is a Behaviour-Driven Development tool for Haskell programmers. BDD is an approach --- to software development that combines Test-Driven Development, Domain Driven Design, and --- Acceptance Test-Driven Planning. Hspec helps you do the TDD part of that equation, focusing --- on the documentation and design aspects of TDD. --- --- Hspec (and the preceding intro) are based on the Ruby library RSpec. Much of what applies to --- RSpec also applies to Hspec. Hspec ties together /descriptions/ of behavior and /examples/ of --- that behavior. The examples can also be run as tests and the output summarises what needs to --- be implemented. --- --- The three functions you'll use the most are 'hspec', 'describe', and 'it'. Here is an --- example of functions that format and unformat phone numbers and the specs for them. --- --- > import Test.Hspec --- > import Test.Hspec.QuickCheck --- > import Test.Hspec.HUnit --- > import Test.QuickCheck hiding (property) --- > import Test.HUnit --- > --- > main = hspec mySpecs --- --- Since the specs are often used to tell you what to implement, it's best to start with --- undefined functions. Once we have some specs, then you can implement each behavior --- one at a time, ensuring that each behavior is met and there is no undocumented behavior. --- --- > unformatPhoneNumber :: String -> String --- > unformatPhoneNumber number = undefined --- > --- > formatPhoneNumber :: String -> String --- > formatPhoneNumber number = undefined --- --- The "describe" function takes a list of behaviors and examples bound together with the "it" function --- --- > mySpecs = describe "unformatPhoneNumber" [ --- --- A boolean expression can act as a behavior's example. --- --- > it "removes dashes, spaces, and parenthesies" --- > (unformatPhoneNumber "(555) 555-1234" == "5555551234"), --- --- The "pending" function marks a behavior as pending an example. The example doesn't count as failing. +-- | +-- Stability: stable -- --- > it "handles non-US phone numbers" --- > (pending "need to look up how other cultures format phone numbers"), +-- Hspec is a testing framework for Haskell. -- --- An HUnit "Test" can act as a behavior's example. (must import @Test.Hspec.HUnit@) +-- This is the library reference for Hspec. +-- The contains more in-depth +-- documentation. +module Test.Hspec ( +-- * Types + Spec +, SpecWith +, Example +, Arg + +-- * Setting expectations +, module Test.Hspec.Expectations + +-- * Defining a spec +, it +, specify +, describe +, context +, example +, parallel +, sequential +, runIO + +-- * Pending spec items +-- | +-- During a test run a /pending/ spec item is: -- --- > it "removes the \"ext\" prefix of the extension" --- > (TestCase $ let expected = "5555551234135" --- > actual = unformatPhoneNumber "(555) 555-1234 ext 135" --- > in assertEqual "remove extension" expected actual), +-- 1. not executed -- --- An @IO()@ action is treated like an HUnit "TestCase". (must import @Test.Hspec.HUnit@) +-- 1. reported as \"pending\" +, pending +, pendingWith +, xit +, xspecify +, xdescribe +, xcontext + +-- * Focused spec items #focus# +-- | +-- During a test run, when a spec contains /focused/ spec items, all other spec +-- items are ignored. +, focus +, fit +, fspecify +, fdescribe +, fcontext + +-- * Hooks +, ActionWith +, before +, before_ +, beforeWith +, beforeAll +, beforeAll_ +, beforeAllWith +, after +, after_ +, afterAll +, afterAll_ +, around +, around_ +, aroundWith +, aroundAll +, aroundAll_ +, aroundAllWith +, mapSubject +, ignoreSubject + +-- * Running a spec +, hspec +) where + +import Test.Hspec.Core.Spec +import Test.Hspec.Core.Hooks +import Test.Hspec.Runner +import Test.Hspec.Expectations + +-- | @example@ is a type restricted version of `id`. It can be used to get better +-- error messages on type mismatches. -- --- > it "converts letters to numbers" --- > (do --- > let expected = "6862377" --- > let actual = unformatPhoneNumber "NUMBERS" --- > assertEqual "letters to numbers" expected actual), +-- Compare e.g. -- --- The "property" function allows a QuickCheck property to act as an example. (must import @Test.Hspec.HUnit@) +-- > it "exposes some behavior" $ example $ do +-- > putStrLn -- --- > it "can add and remove formatting without changing the number" --- > (property $ forAll phoneNumber $ --- > \ n -> unformatPhoneNumber (formatPhoneNumber n) == n) --- > ] --- > --- > phoneNumber :: Gen String --- > phoneNumber = do --- > nums <- elements [7,10,11,12,13,14,15] --- > vectorOf nums (elements "0123456789") +-- with -- -module Test.Hspec ( - -- types - Spec(), Result(), - -- the main api - describe, it, hspec, pending, descriptions, - -- alternate "runner" functions - hHspec, hspecX, hspecB, pureHspec, pureHspecB -) where - -import Test.Hspec.Internal +-- > it "exposes some behavior" $ do +-- > putStrLn +example :: Expectation -> Expectation +example = id diff --git a/src/Test/Hspec/Discover.hs b/src/Test/Hspec/Discover.hs new file mode 100644 --- /dev/null +++ b/src/Test/Hspec/Discover.hs @@ -0,0 +1,35 @@ +{-# OPTIONS_GHC -fno-warn-deprecations #-} +{-# OPTIONS_HADDOCK hide #-} +{-# LANGUAGE FlexibleInstances #-} +module Test.Hspec.Discover {-# WARNING + "This module is used by @hspec-discover@. It is not part of the public API and may change at any time." + #-} ( + Spec +, hspec +, IsFormatter (..) +, hspecWithFormatter +, postProcessSpec +, describe +, module Prelude +) where + +import Test.Hspec.Core.Spec +import Test.Hspec.Core.Runner +import Test.Hspec.Core.Formatters.V1 + +class IsFormatter a where + toFormatter :: a -> IO Formatter + +instance IsFormatter (IO Formatter) where + toFormatter = id + +instance IsFormatter Formatter where + toFormatter = return + +hspecWithFormatter :: IsFormatter a => a -> Spec -> IO () +hspecWithFormatter formatter spec = do + f <- toFormatter formatter + hspecWith defaultConfig {configFormatter = Just f} spec + +postProcessSpec :: FilePath -> Spec -> Spec +postProcessSpec _ = id diff --git a/src/Test/Hspec/Formatters.hs b/src/Test/Hspec/Formatters.hs new file mode 100644 --- /dev/null +++ b/src/Test/Hspec/Formatters.hs @@ -0,0 +1,8 @@ +{-# OPTIONS_GHC -fno-warn-deprecations #-} +-- | +-- Stability: deprecated +module Test.Hspec.Formatters +{-# DEPRECATED "Use [Test.Hspec.Api.Formatters.V1](https://hackage.haskell.org/package/hspec-api/docs/Test-Hspec-Api-Formatters-V1.html) instead." #-} +(module Test.Hspec.Core.Formatters.V1) +where +import Test.Hspec.Core.Formatters.V1 diff --git a/src/Test/Hspec/HUnit.hs b/src/Test/Hspec/HUnit.hs deleted file mode 100644 --- a/src/Test/Hspec/HUnit.hs +++ /dev/null @@ -1,34 +0,0 @@ -{-# OPTIONS -XFlexibleInstances -fno-warn-orphans #-} - --- | Importing this module allows you to use an @HUnit@ test case as an example --- for a behavior. You can use an explicit @TestCase@ data constructor or --- use an @IO()@ action. For an @IO()@ action, any exception means the example --- failed; otherwise, it's successfull. --- --- > describe "cutTheDeck" [ --- > it "puts the first half of a list after the last half" --- > (TestCase $ assertEqual "cut the deck" [3,4,1,2] (cutTheDeck [1,2,3,4])), --- > --- > it "restores an even sized list when cut twice" --- > (assertEqual "cut the deck twice" [3,4,1,2] (cutTheDeck (cutTheDeck [1,2,3,4]))), --- > ] --- > -module Test.Hspec.HUnit ( -) where - -import Test.Hspec.Internal -import qualified Test.HUnit as HU -import Data.List (intersperse) - -instance SpecVerifier (IO ()) where - it description example = it description (HU.TestCase example) - -instance SpecVerifier HU.Test where - it description example = do - (counts, fails) <- HU.runTestText HU.putTextToShowS example - if HU.errors counts + HU.failures counts == 0 - then return (description, Success) - else return (description, Fail (details $ fails "")) - -details :: String -> String -details = concat . intersperse "\n" . tail . init . lines diff --git a/src/Test/Hspec/Internal.hs b/src/Test/Hspec/Internal.hs deleted file mode 100644 --- a/src/Test/Hspec/Internal.hs +++ /dev/null @@ -1,190 +0,0 @@ -{-# OPTIONS -XFlexibleInstances #-} - -module Test.Hspec.Internal where - -import System.IO -import System.Exit -import Data.List (mapAccumL, groupBy, intersperse) -import System.CPUTime (getCPUTime) -import Text.Printf -import Control.Exception -import Control.Monad (liftM) - --- | The result of running an example. -data Result = Success | Fail String | Pending String - deriving Eq - - --- | Everything needed to specify and show a specific behavior. -data Spec = Spec { - -- | What is being tested, usually the name of a type. - name::String, - -- | The specific behavior being tested. - requirement::String, - -- | The status of this behavior. - result::Result } - - --- | Create a set of specifications for a specific type being described. --- Once you know what you want specs for, use this. --- --- > describe "abs" [ --- > it "returns a positive number given a negative number" --- > (abs (-1) == 1) --- > ] --- -describe :: String -- ^ The name of what is being described, usually a function or type. - -> [IO (String, Result)] -- ^ A list of behaviors and examples, created by a list of 'it'. - -> IO [Spec] -describe n ss = do - ss' <- sequence ss - return $ map (\ (req, res) -> Spec n req res) ss' - --- | Combine a list of descriptions. -descriptions :: [IO [Spec]] -> IO [Spec] -descriptions = liftM concat . sequence - --- | Evaluate a Result. Any exceptions (undefined, etc.) are treated as failures. -safely :: Result -> IO Result -safely f = Control.Exception.catch ok failed - where ok = f `seq` return f - failed e = return $ Fail (show (e :: SomeException)) - - --- | Anything that can be used as an example of a behavior. -class SpecVerifier a where - -- | Create a description and example of a behavior, a list of these - -- is used by 'describe'. Once you know what you want to specify, use this. - -- - -- > describe "closeEnough" [ - -- > it "is true if two numbers are almost the same" - -- > (1.001 `closeEnough` 1.002), - -- > - -- > it "is false if two numbers are not almost the same" - -- > (not $ 1.001 `closeEnough` 1.003) - -- > ] - -- - it :: String -- ^ A description of this behavior. - -> a -- ^ An example for this behavior. - -> IO (String, Result) - - -instance SpecVerifier Bool where - it description example = do - r <- safely (if example then Success else Fail "") - return (description, r) - -instance SpecVerifier Result where - it description example = return (description, example) - - --- | Declare an example as not successful or failing but pending some other work. --- If you want to report on a behavior but don't have an example yet, use this. --- --- > describe "fancyFormatter" [ --- > it "can format text in a way that everyone likes" --- > (pending "waiting for clarification from the designers") --- > ] --- -pending :: String -- ^ An explanation for why this behavior is pending. - -> Result -pending = Pending - - --- | Create a document of the given specs. -documentSpecs :: [Spec] -> [String] -documentSpecs specs = lines $ unlines $ concat report ++ [""] ++ intersperse "" errors - where organize = groupBy (\ a b -> name a == name b) - (errors, report) = mapAccumL documentGroup [] $ organize specs - --- | Create a document of the given group of specs. -documentGroup :: [String] -> [Spec] -> ([String], [String]) -documentGroup errors specGroup = (errors', "" : name (head specGroup) : report) - where (errors', report) = mapAccumL documentSpec errors specGroup - --- | Create a document of the given spec. -documentSpec :: [String] -> Spec -> ([String], String) -documentSpec errors spec = case result spec of - Success -> (errors, " - " ++ requirement spec) - Fail s -> (errors ++ [errorDetails s], " x " ++ requirement spec ++ errorTag) - Pending s -> (errors, " - " ++ requirement spec ++ "\n # " ++ s) - where errorTag = " [" ++ (show $ length errors + 1) ++ "]" - errorDetails s = concat [ show (length errors + 1), ") ", name spec, - " ", requirement spec, " FAILED", - if null s then "" else "\n" ++ s ] - - --- | Create a summary of how long it took to run the examples. -timingSummary :: Double -> String -timingSummary t = printf "Finished in %1.4f seconds" (t / (10.0^(12::Integer)) :: Double) - -failedCount :: [Spec] -> Int -failedCount ss = length $ filter (isFailure.result) ss - where - isFailure (Fail _) = True - isFailure _ = False - --- | Create a summary of how many specs exist and how many examples failed. -successSummary :: [Spec] -> String -successSummary ss = quantify (length ss) "example" ++ ", " ++ quantify (failedCount ss) "failure" - - --- | Create a document of the given specs. --- This does not track how much time it took to check the examples. If you want --- a description of each spec and don't need to know how long it tacks to check, --- use this. -pureHspec :: [Spec] -- ^ The specs you are interested in. - -> [String] -pureHspec = fst . pureHspecB - - -pureHspecB :: [Spec] -- ^ The specs you are interested in. - -> ([String], Bool) -pureHspecB ss = (report, failedCount ss == 0) - where report = documentSpecs ss ++ [ "", timingSummary 0, "", successSummary ss] - - --- | Create a document of the given specs and write it to stdout. --- This does track how much time it took to check the examples. Use this if --- you want a description of each spec and do need to know how long it tacks --- to check the examples or want to write to stdout. -hspec :: IO [Spec] -> IO () -hspec ss = hspecB ss >> return () - --- | Same as 'hspec' except it returns a bool indicating if all examples ran without failures -hspecB :: IO [Spec] -> IO Bool -hspecB = hHspec stdout - --- | Same as 'hspec' except the program exits successfull if all examples ran without failures or --- with an errorcode of 1 if any examples failed. -hspecX :: IO [Spec] -> IO a -hspecX ss = hspecB ss >>= exitWith . toExitCode - -toExitCode :: Bool -> ExitCode -toExitCode True = ExitSuccess -toExitCode False = ExitFailure 1 - - --- | Create a document of the given specs and write it to the given handle. --- This does track how much time it took to check the examples. Use this if --- you want a description of each spec and do need to know how long it tacks --- to check the examples or want to write to a file or other handle. --- --- > writeReport filename specs = withFile filename WriteMode (\ h -> hHspec h specs) --- -hHspec :: Handle -- ^ A handle for the stream you want to write to. - -> IO [Spec] -- ^ The specs you are interested in. - -> IO Bool -hHspec h ss = do - t0 <- getCPUTime - ss' <- ss - mapM_ (hPutStrLn h) $ documentSpecs ss' - t1 <- getCPUTime - mapM_ (hPutStrLn h) [ "", timingSummary (fromIntegral $ t1 - t0), "", successSummary ss'] - return $ failedCount ss' == 0 - - --- | Create a more readable display of a quantity of something. -quantify :: Num a => a -> String -> String -quantify 1 s = "1 " ++ s -quantify n s = show n ++ " " ++ s ++ "s" diff --git a/src/Test/Hspec/QuickCheck.hs b/src/Test/Hspec/QuickCheck.hs --- a/src/Test/Hspec/QuickCheck.hs +++ b/src/Test/Hspec/QuickCheck.hs @@ -1,34 +1,60 @@ +{-# LANGUAGE FlexibleContexts #-} +{-# LANGUAGE ConstraintKinds #-} +module Test.Hspec.QuickCheck ( +-- * Params + modifyArgs +, modifyMaxSuccess +, modifyMaxDiscardRatio +, modifyMaxSize +, modifyMaxShrinks --- | Importing this module allows you to use a QuickCheck property as an example --- for a behavior. Use the 'property' function to indicate a QuickCkeck property. +-- * Shortcuts +, prop +, xprop +, fprop +) where + +import Test.Hspec +import Test.QuickCheck +import Test.Hspec.Core.QuickCheck + +-- | +-- > prop ".." $ +-- > .. -- --- > describe "cutTheDeck" [ --- > it "puts the first half of a list after the last half" --- > (property $ \ xs -> let top = take (length xs `div` 2) xs --- > bot = drop (length xs `div` 2) xs --- > in cutTheDeck xs == bot ++ top), --- > --- > it "restores an even sized list when cut twice" --- > (property $ \ xs -> even (length xs) ==> cutTheDeck (cutTheDeck xs) == xs) --- > ] +-- is a shortcut for -- -module Test.Hspec.QuickCheck ( - property -) where +-- @ +-- `it` ".." $ `property` $ +-- .. +-- @ +prop :: (HasCallStack, Testable prop) => String -> prop -> Spec +prop s = it s . property -import Test.Hspec.Internal -import qualified Test.QuickCheck as QC -data QuickCheckProperty a = QuickCheckProperty a +-- | +-- > xprop ".." $ +-- > .. +-- +-- is a shortcut for +-- +-- @ +-- `xit` ".." $ `property` $ +-- .. +-- @ +xprop :: (HasCallStack, Testable prop) => String -> prop -> Spec +xprop s = xit s . property -property :: QC.Testable a => a -> QuickCheckProperty a -property = QuickCheckProperty -instance QC.Testable t => SpecVerifier (QuickCheckProperty t) where - it description (QuickCheckProperty prop) = do - r <- QC.quickCheckResult prop - case r of - QC.Success {} -> return (description, Success) - f@(QC.Failure {}) -> return (description, Fail (QC.output f)) - g@(QC.GaveUp {}) -> return (description, Fail ("Gave up after " ++ quantify (QC.numTests g) "test" )) - QC.NoExpectedFailure {} -> return (description, Fail ("No expected failure")) +-- | +-- > fprop ".." $ +-- > .. +-- +-- is a shortcut for +-- +-- @ +-- `fit` ".." $ `property` $ +-- .. +-- @ +fprop :: (HasCallStack, Testable prop) => String -> prop -> Spec +fprop s = fit s . property diff --git a/src/Test/Hspec/Runner.hs b/src/Test/Hspec/Runner.hs new file mode 100644 --- /dev/null +++ b/src/Test/Hspec/Runner.hs @@ -0,0 +1,2 @@ +module Test.Hspec.Runner (module Test.Hspec.Core.Runner) where +import Test.Hspec.Core.Runner diff --git a/version.yaml b/version.yaml new file mode 100644 --- /dev/null +++ b/version.yaml @@ -0,0 +1,7 @@ +version: &version 2.11.17 +synopsis: A Testing Framework for Haskell +author: Simon Hengel +maintainer: Simon Hengel +category: Testing +stability: experimental +homepage: https://hspec.github.io/