{"id":13491782,"url":"https://github.com/stoeffel/elm-verify-examples","last_synced_at":"2025-05-08T00:40:03.615Z","repository":{"id":13301931,"uuid":"74123320","full_name":"stoeffel/elm-verify-examples","owner":"stoeffel","description":null,"archived":false,"fork":false,"pushed_at":"2024-04-16T07:59:35.000Z","size":19262,"stargazers_count":166,"open_issues_count":15,"forks_count":14,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-05-08T00:39:57.451Z","etag":null,"topics":["doctest","elm","elm-test","verify"],"latest_commit_sha":null,"homepage":null,"language":"Elm","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stoeffel.png","metadata":{"files":{"readme":"Readme.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-11-18T11:17:58.000Z","updated_at":"2024-11-19T14:36:43.000Z","dependencies_parsed_at":"2024-01-22T08:58:40.759Z","dependency_job_id":"c45645a9-c5bb-49c3-ab37-7d036deda6ad","html_url":"https://github.com/stoeffel/elm-verify-examples","commit_stats":null,"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stoeffel%2Felm-verify-examples","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stoeffel%2Felm-verify-examples/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stoeffel%2Felm-verify-examples/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stoeffel%2Felm-verify-examples/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stoeffel","download_url":"https://codeload.github.com/stoeffel/elm-verify-examples/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252978668,"owners_count":21834910,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["doctest","elm","elm-test","verify"],"created_at":"2024-07-31T19:01:00.179Z","updated_at":"2025-05-08T00:40:03.591Z","avatar_url":"https://github.com/stoeffel.png","language":"Elm","funding_links":[],"categories":["Elm"],"sub_categories":[],"readme":"# elm-verify-examples [![Build Status](https://travis-ci.org/stoeffel/elm-verify-examples.svg?branch=master)](https://travis-ci.org/stoeffel/elm-verify-examples)\n\n\u003e Verify examples in your docs.\n\n:information_source: This was formerly known as `elm-doc-test`.\n\n:warning: This is not a replacement for tests, this tool should be used for improving your documentation.\n\n## Install\n\n```bash\n$ npm i elm-test -g\n$ npm i elm-verify-examples -g\n$ elm-test init\n```\n\n## Setup\n\nThere is no need for any configuration. elm-verify-examples will run on all elm files in the specified `source-directories` (`elm.json`). It's possible to create a config file if you want to run it on only a subset of files or on additional markdown files.\n\n```bash\n$ touch tests/elm-verify-examples.json\n```\n\n`elm-verify-examples.json` contains information on which files contain verified examples and where to find them.\n\n```json\n{\n  \"tests\": [\"Mock\", \"Mock.Foo.Bar.Moo\", \"./README.md\"]\n}\n```\n\nAlternatively you can run elm-verify-examples on all elm files in your source directories:\n\n```json\n{\n  \"tests\": \"all\"\n}\n```\n\nor\n\n```json\n{\n  \"tests\": [\"all\", \"Some.md\"]\n}\n```\n\nIt's recommended to add `./tests/VerifyExamples` to your `.gitignore`.\n\nIf you are building a _package_, you can pass the string `\"exposed\"` instead of an explicit list of modules,\nthis will cause all the documented modules in your package to be verified. This makes it easier to keep these in\nsync.\n\n## Writing Verified Examples\n\nVerified examples look like normal code examples in doc-comments. \\\nCode needs to be indented by 4 spaces.\nYou can specify the expected result of an expression, by adding a comment `--\u003e` (the `\u003e` is important) and an expected expression.\n\n```elm\n{-| returns the sum of two int.\n\n    -- You can write the expected result on the next line,\n\n    add 41 1\n    --\u003e 42\n\n    -- or on the same line.\n\n    add 3 3 --\u003e 6\n\n-}\n\n\nadd : Int -\u003e Int -\u003e Int\nadd =\n    (+)\n```\n\n### Multiline Examples\n\nYou can write examples on multiple lines.\n\n```elm\n{-| reverses the list\n\n    rev\n        [ 41\n        , 1\n        ]\n    --\u003e [ 1\n    --\u003e , 41\n    --\u003e ]\n\n    rev [1, 2, 3]\n        |\u003e List.map toString\n        |\u003e String.concat\n    --\u003e \"321\"\n\n-}\n\n\nrev : List a -\u003e List a\nrev =\n    List.reverse\n```\n\n### Imports\n\nYou can specify imports, if you want to use a module or a special test util.\n\n```elm\n{-|\n\n    import Dict\n\n    myWeirdFunc (Dict.fromList [(1, \"a\"), (2, \"b\")]) [2, 1]\n    --\u003e \"ba\"\n\n-}\n```\n\n### Intermediate Definitions\n\nYou can use intermediate definitions in your example.\n:information: Unused functions don't get added to the test. This is useful if you wanna add incomplete examples to your docs.\n:warning: Intermediate definitions need a type signature!\n\n```elm\n{-|\n\n    isEven : Int -\u003e Bool\n    isEven n =\n        remainderBy 2 n == 0\n\n    List.Extra.filterNot isEven [1,2,3,4] --\u003e [1,3]\n\n-}\n\n\nfilterNot : (a -\u003e Bool) -\u003e List a -\u003e List a\n```\n\n### Types in Examples\n\nYou can define union types and type aliases in your examples.\n\n```elm\n{-| With a union type in the example.\ntype Animal\n= Dog\n| Cat\n\n    double Dog\n    --\u003e (Dog, Dog)\n\n-}\n\n\ndouble : a -\u003e ( a, a )\ndouble a =\n    ( a, a )\n```\n\n```elm\n{-| With a type alias in the example.\n\n    customTypeAlias defaultUser \"?\"\n    --\u003e \"?Luke\"\n\n    type alias User =\n        { id: Int -- ID\n        , name: String\n        }\n\n    defaultUser : User\n    defaultUser =\n        { id = 1\n        , name = \"Luke\"\n        }\n\n    customTypeAlias defaultUser \"_\"\n    --\u003e \"_Luke\"\n\n-}\n\n\ncustomTypeAlias : { a | name : String } -\u003e String -\u003e String\ncustomTypeAlias { name } prefix =\n    prefix ++ name\n```\n\n### Examples in markdown files\n\nYou can also verify code example in markdown files (such as your README). To do so, add the file's path to your `elm-verify-examples.json` file and write your example using the sames rules as above (no need for 4-space indentation here).\n\n````\nThis is my README!\nIt explains how the `Documented` module works:\n\n```elm\nimport Documented\n\nDocumented.two --\u003e 2\n```\n````\n\n## Verify Examples\n\n`elm-verify-examples` converts your verify-examples into elm-tests, and optionally runs them using `elm-test`. To only generate the test files in `tests/VerifyExamples/`:\n\n```bash\n$ elm-verify-examples\n```\n\nThis is useful if you want to run your tests using different runner than `elm-test`, e.g. `elm-coverage`. If you also want to run the generated tests:\n\n```bash\n$ elm-verify-examples --run-tests\n```\n\nNote that this way the test files will be removed after they are ran.\n\nBy default, this command looks for the config file at `tests/elm-verify-examples.json`. If you want it to load a specific config file use the `--config` argument (e.g. `elm-verify-examples --config my/custom/path/elm-verify-examples.json` will read the config from `my/custom/path/elm-verify-examples.json`).\n\nYou can run elm-verify-examples for one or more modules explicitly. They don't have to be specified in `tests/elm-verify-examples.json`.\n\n```bash\n$ elm-verify-examples ./src/Foo.elm ./src/Foo/Bar.elm\n```\n\nYou can pass a custom path to elm-test if necessary.\n\n```bash\n$ elm-verify-examples --elm-test=./node_modules/.bin/elm-test\n$ # or add it to your elm-verify-examples.json `elmTest: \"../node....`\n$ # you can also pass arguments to elm-test with --elm-test-args\n```\n\nIt will use the elm-test installed with this package.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstoeffel%2Felm-verify-examples","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstoeffel%2Felm-verify-examples","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstoeffel%2Felm-verify-examples/lists"}