Initial commit

.github/workflows/build.yml

@@ -0,0 +1,49 @@
+name: build
+run-name: Build Bam
+on: [push]
+
+# Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+permissions:
+  contents: write
+
+jobs:
+  build_matrix:
+    runs-on: ubuntu-latest    
+    strategy:
+      matrix:
+        ocaml-compiler: [
+            # OCaml LTS version
+            ocaml.4.14.1,
+            # ocaml-system for Fedora 39
+            ocaml.5.0.0,
+            # ocaml-system for Archlinux
+            ocaml.5.1.0
+          ]
+    steps:
+      - uses: actions/checkout@v4
+      - name: setting up opam...
+        uses: ocaml/setup-ocaml@v2
+        with:
+          ocaml-compiler: ${{ matrix.ocaml-compiler }}
+      - name: Install dependencies
+        run: |
+          opam update
+          opam upgrade
+          opam install . --deps-only -t
+      - name: Build Bam
+        run: |
+          eval $(opam env)
+          dune build .
+      - name: Test
+        run: |
+          eval $(opam env)
+          dune runtest
+      - name: Build documentation
+        run: |
+          eval $(opam env)
+          opam install odoc
+          dune build @doc
+      - name: Deploy 🚀
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          folder: _build/default/_doc/_html

.gitignore

@@ -0,0 +1,102 @@
+*.annot
+*.cmo
+*.cma
+*.cmi
+*.a
+*.o
+*.cmx
+*.cmxs
+*.cmxa
+
+# ocamlbuild working directory
+_build/
+
+# ocamlbuild targets
+*.byte
+*.native
+
+# oasis generated files
+setup.data
+setup.log
+
+# Merlin configuring file for Vim and Emacs
+.merlin
+
+# Dune generated files
+*.install
+
+# Local OPAM switch
+_opam/
+
+# -*- mode: gitignore; -*-
+*~
+\#*\#
+/.emacs.desktop
+/.emacs.desktop.lock
+*.elc
+auto-save-list
+tramp
+.\#*
+
+# Org-mode
+.org-id-locations
+*_archive
+
+# flymake-mode
+*_flymake.*
+
+# eshell files
+/eshell/history
+/eshell/lastdir
+
+# elpa packages
+/elpa/
+
+# reftex files
+*.rel
+
+# AUCTeX auto folder
+/auto/
+
+# cask packages
+.cask/
+dist/
+
+# Flycheck
+flycheck_*.el
+
+# server auth directory
+/server/
+
+# projectiles files
+.projectile
+
+# directory configuration
+.dir-locals.el
+
+# network security
+/network-security.data
+
+# docusaurus
+.log
+.nojekyll
+
+node_modules
+/coverage
+/_export
+/_esy
+/_build
+/_release
+/_platformrelease
+/bin/fastreplacestring
+.merlin
+npm-debug.log
+yarn-error.log
+*.install
+.esy-bash-path
+test-e2e-re/lib/verdaccio/storage
+*~
+
+# script files to automate local testing
+dev.sh
+dev.ps1

.ocamlformat

@@ -0,0 +1,2 @@
+version=0.26.1
+profile=ocamlformat

CHANGES

@@ -0,0 +1,6 @@
+Changelog for Bam library
+
+## v0.1 (2024-01-24)
+
+- Initial release of the Bam library.
+

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 François Thiré
+
+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:
+
+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.

README.md

@@ -0,0 +1,51 @@
+# Bam - Property-Based Testing Library for OCaml
+
+## Overview
+
+Bam is an OCaml library designed for writing property-based tests. It
+simplifies the process of defining and using generators for tests,
+offering a monad-like structure that integrates seamlessly with
+shrinking strategies. This design aims to make shrinking both
+predictable and effective, thereby enhancing the debugging experience.
+
+
+## Key Features
+
+- Standard Module: The {!module:Std} module provides some basic
+  generators with predefined shrinking strategies
+
+- Monad-like Generators: The library enables easy creation of new
+  generators, following a monad-like pattern that works harmoniously
+  with shrinking mechanisms.
+
+- Shrinking Strategies: Various default shrinking strategies are
+  available, aiding in the efficient identification of minimal
+  counter-examples.
+
+- Custom Shrinkers: The {!Gen} module allows for the definition of
+  ad-hoc shrinkers.
+
+- Documentation on Shrinking: For those interested in understanding
+  the intricacies of shrinking within this library, a detailed primer
+  is available [here](https://francoisthire.github.io/bam/bam/shrinking.html).
+
+## Installation
+
+### With opam
+
+```bash
+opam install bam tezt-bam
+```
+
+
+## Usage
+
+[Basic examples or a quick-start guide on how to use the library]
+
+## Contributing
+
+[Guidelines for contributing to the library]
+
+## License
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

bam.opam

@@ -0,0 +1,35 @@
+# This file is generated by dune, edit dune-project instead
+opam-version: "2.0"
+synopsis: "A property-based testing library with internal shrinking"
+description:
+  "A property-based testing allowing to define generators with internal shrinking easily"
+maintainer: ["François Thiré"]
+authors: ["François Thiré"]
+license: "MIT"
+tags: ["test" "pbt" "shrinking" "internal"]
+homepage: "https://github.com/francoisthire/bam"
+doc: "https://francoisthire.github.io/bam/"
+bug-reports: "https://github.com/francoisthire/bam/issues"
+depends: [
+  "ocaml"
+  "dune" {>= "3.7"}
+  "pringo"
+  "zarith"
+  "odoc" {with-doc}
+  "tezt" {with-test}
+]
+build: [
+  ["dune" "subst"] {dev}
+  [
+    "dune"
+    "build"
+    "-p"
+    name
+    "-j"
+    jobs
+    "@install"
+    "@runtest" {with-test}
+    "@doc" {with-doc}
+  ]
+]
+dev-repo: "git+https://github.com/francoisthire/bam.git"

dune-project

@@ -0,0 +1,35 @@
+(lang dune 3.7)
+
+(name bam)
+
+(generate_opam_files true)
+
+(source
+ (github francoisthire/bam))
+
+(authors "François Thiré")
+
+(maintainers "François Thiré")
+
+(license MIT)
+
+(documentation https://francoisthire.github.io/bam/)
+
+(package
+ (name bam)
+ (synopsis "A property-based testing library with internal shrinking")
+ (description "A property-based testing allowing to define generators with internal shrinking easily")
+ (depends ocaml dune pringo zarith (odoc :with-doc) (tezt :with-test))
+ (tags
+  (test pbt shrinking internal)))
+
+(package
+ (name tezt-bam)
+ (synopsis "A plugin of [bam] for Tezt")
+ (description "Provides a way to register PBT tests with Tezt")
+ (depends ocaml dune tezt bam mtime (odoc :with-doc))
+ (tags
+  (test tezt pbt shrinking internal bam)))
+
+
+; See the complete stanza docs at https://dune.readthedocs.io/en/stable/dune-files.html#dune-project

example/1-simple/README.md

@@ -0,0 +1,27 @@
+# 1-simple
+
+A simple example on how to use the library.
+
+```ocaml
+open Tezt_bam
+
+let register () =
+  let gen = Std.int () in
+  let property _x = Ok () in
+  Pbt.register ~__FILE__ ~title:"Simple example of bam" ~tags:["bam"; "simple"]
+    ~gen ~property ()	
+```
+
+You can run the example with:
+
+```bash
+$ dune exec example/main.exe -- simple
+[14:05:37.035] [SUCCESS] (1/1) Simple example of bam
+```
+
+The test run successfully!
+
+**Next steps:**
+- The next example [2-simple-failure]() will investigate how to debug
+  a test when the property fails.
+

example/1-simple/dune

@@ -0,0 +1,3 @@
+(library
+  (name simple)
+  (libraries tezt-bam))

example/1-simple/simple.ml

@@ -0,0 +1,7 @@
+open Tezt_bam
+
+let register () =
+  let gen = Std.int () in
+  let property _x = Ok () in
+  Pbt.register ~__FILE__ ~title:"Simple example of bam" ~tags:["bam"; "simple"]
+    ~gen ~property ()