{"id":13393278,"url":"https://github.com/brian-watkins/elm-spec","last_synced_at":"2025-10-29T18:31:30.550Z","repository":{"id":36475270,"uuid":"198616838","full_name":"brian-watkins/elm-spec","owner":"brian-watkins","description":"Describe the behavior of Elm programs","archived":false,"fork":false,"pushed_at":"2023-08-19T03:11:51.000Z","size":5996,"stargazers_count":32,"open_issues_count":16,"forks_count":4,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-02-02T04:11:10.684Z","etag":null,"topics":["elm","testing"],"latest_commit_sha":null,"homepage":"https://package.elm-lang.org/packages/brian-watkins/elm-spec/latest/","language":"Elm","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/brian-watkins.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"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}},"created_at":"2019-07-24T10:52:51.000Z","updated_at":"2025-01-29T11:22:29.000Z","dependencies_parsed_at":"2024-01-05T22:00:45.943Z","dependency_job_id":"86d0c4c7-17bb-45b4-af11-37c7e7d01c57","html_url":"https://github.com/brian-watkins/elm-spec","commit_stats":{"total_commits":722,"total_committers":5,"mean_commits":144.4,"dds":0.03324099722991691,"last_synced_commit":"e6c929c709cd3ad4afb072e2fb337ee8e6057472"},"previous_names":[],"tags_count":65,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brian-watkins%2Felm-spec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brian-watkins%2Felm-spec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brian-watkins%2Felm-spec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brian-watkins%2Felm-spec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/brian-watkins","download_url":"https://codeload.github.com/brian-watkins/elm-spec/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238874223,"owners_count":19545138,"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":["elm","testing"],"created_at":"2024-07-30T17:00:48.495Z","updated_at":"2025-10-29T18:31:28.252Z","avatar_url":"https://github.com/brian-watkins.png","language":"Elm","funding_links":[],"categories":["Elm","Testing"],"sub_categories":["Individual Podcast episodes"],"readme":"# elm-spec\n\nUse elm-spec to write specs that describe the behavior of your Elm program.\n\nYou think TDD/BDD is great, and maybe you're already writing tests in Elm or using tools like Cypress\nto test your program end-to-end. Why use elm-spec?\n\n- elm-spec allows you to describe behaviors that involve HTML, browser navigation, HTTP, Time, ports,\ncommands, and subscriptions -- and there's no need to structure your code in any special way\nto do so (although you can if you wish).\n- elm-spec does not simulate calls to your program's `view` or `update` functions, and it lets the\nElm runtime handle commands and subscriptions; your program interacts with the Elm runtime just as it\nwould in production.\n- elm-spec exercises your program in a DOM environment (JSDOM or a web browser).\n- elm-spec allows you to write specs that describe the behavior of parts of your program in isolation from others. This makes those specs easier to write and easier to understand.\n\nIn short, with elm-spec you get the confidence you would from a browser-based\nend-to-end testing tool like Cypress, without losing the convenience of elm-based testing tools. You can\nstill write your specs in Elm and you can still test parts of your code in isolation, but your specs\nrun in a browser and they exercise your code just like it will be exercised in production.\n\n\n## Getting Started\n\n1. Create a directory called `specs` for your specs and change into that directory.\n\n2. Initialize a new elm app with `elm init`. Add your program's source\ndirectory to the `source-directories` field of `elm.json`.\n\n3. Install elm-spec: `elm install brian-watkins/elm-spec`.\n\n4. Install any other dependencies your app needs.\n\n5. Add a file called `Runner.elm` to your specs src directory. It should look something like this:\n\n```\nport module Runner exposing\n  ( program\n  , browserProgram\n  , skip\n  , pick\n  )\n\nimport Spec exposing (Message)\n\nport elmSpecOut : Message -\u003e Cmd msg\nport elmSpecIn : (Message -\u003e msg) -\u003e Sub msg\nport elmSpecPick : () -\u003e Cmd msg\n\nconfig : Spec.Config msg\nconfig =\n  { send = elmSpecOut\n  , listen = elmSpecIn\n  }\n\npick =\n  Spec.pick elmSpecPick\n\nskip =\n  Spec.skip\n\nprogram =\n  Spec.program config\n\nbrowserProgram =\n  Spec.browserProgram config\n```\n\nYou must create the `elmSpecOut` and `elmSpecIn` ports and provide them to `Spec.program` or `Spec.browserProgram` via a `Spec.Config` value.\n\nYou must also create the `elmSpecPick` port and provide it to `Spec.pick`.\n\nNow you can write spec modules. Each spec module is an elm program and so must have a `main` function. To construct\nthe `main` function, just reference `program` or `browserProgram` from your `Runner.elm` and\nprovide a `List Spec` to run.\n\nDuring the course of development, it's often useful to run only certain scenarios.\nIn that case, use `pick` from your `Runner.elm` to designate those scenarios. See the docs for `Spec.pick`\nfor more information.\n\nYou can also skip scenarios, if you like, by using `Spec.skip`.\n\nHere's an example spec module:\n\n```\nmodule SampleSpec exposing (main)\n\nimport Spec exposing (..)\nimport Spec.Setup as Setup\nimport Spec.Markup as Markup\nimport Spec.Markup.Selector exposing (..)\nimport Spec.Markup.Event as Event\nimport Spec.Claim as Claim\nimport Runner\nimport Main as App\n\n\nclickSpec : Spec App.Model App.Msg\nclickSpec =\n  describe \"an html program\"\n  [ scenario \"a click event\" (\n      given (\n        Setup.initWithModel App.defaultModel\n          |\u003e Setup.withUpdate App.update\n          |\u003e Setup.withView App.view\n      )\n      |\u003e when \"the button is clicked three times\"\n        [ Markup.target \u003c\u003c by [ id \"my-button\" ]\n        , Event.click\n        , Event.click\n        , Event.click\n        ]\n      |\u003e it \"renders the count\" (\n        Markup.observeElement\n          |\u003e Markup.query \u003c\u003c by [ id \"count-results\" ]\n          |\u003e expect (\n            Claim.isSomethingWhere \u003c|\n            Markup.text \u003c|\n            Claim.isStringContaining 1 \"You clicked the button 3 time(s)\"\n          )\n      )\n    )\n  ]\n\nmain =\n  Runner.browserProgram\n    [ clickSpec\n    ]\n```\n\n## Running Specs\n\nTo run your specs, you need to install a runner. There are currently two options.\n\n### elm-spec-runner\n\nYou can run your specs in JSDOM or a real browser, right from the command line.\n\n```\n$ npm install --save-dev elm-spec-runner\n```\n\nThen, assuming your specs are in a directory called `./specs`, just run your spec suite like so:\n\n```\n$ npx elm-spec\n```\n\nBy default, elm-spec-runner will execute your specs in a [JSDOM](https://github.com/jsdom/jsdom) environment.\nYou can configure elm-spec-runner to execute your specs in a real browser via a command line option;\nchromium, webkit, and firefox are all available.\n\nSee [elm-spec-runner](https://github.com/brian-watkins/elm-spec/tree/master/runner/elm-spec-runner) for more\ndetails on command line options.\n\n### karma-elm-spec-framework\n\nYou can also run your specs in a real browser via [Karma](http://karma-runner.github.io/latest/).\n\nSee [karma-elm-spec-framework](https://github.com/brian-watkins/elm-spec/tree/master/runner/karma-elm-spec-framework)\nfor more details.\n\n\n## More Examples\n\nFor more examples, see the [docs for elm-spec](https://package.elm-lang.org/packages/brian-watkins/elm-spec/latest/).\nIn particular, there are examples demonstrating how to describe behavior related to [HTTP requests](https://package.elm-lang.org/packages/brian-watkins/elm-spec/latest/Spec-Http), describe behavior related to [ports](https://package.elm-lang.org/packages/brian-watkins/elm-spec/latest/Spec-Port), observe [navigation changes](https://package.elm-lang.org/packages/brian-watkins/elm-spec/latest/Spec-Navigator#location), control [time](https://package.elm-lang.org/packages/brian-watkins/elm-spec/latest/Spec-Time) during a spec, select and work with [files and downloads](https://package.elm-lang.org/packages/brian-watkins/latest/Spec-File), and use [witnesses](https://package.elm-lang.org/packages/brian-watkins/elm-spec/latest/Spec-Witness) to ensure one part of a program acts in an expected way.\n\nFor even more examples, see the [specs for elm-spec](https://github.com/brian-watkins/elm-spec/tree/master/tests/src/Specs).\n\nFor a real-world test suite, see the [specs for a simple code-guessing game](https://github.com/brian-watkins/mindmaster).\n\n\n## Extra\n\nI suggest adding one more file to your spec suite: `Spec/Extra.elm`.\n\n```\nmodule Spec.Extra exposing (equals)\n\nimport Spec.Claim as Claim exposing (Claim)\n\nequals : a -\u003e Claim a\nequals =\n  Claim.isEqual Debug.toString\n```\n\nThen, you can import the `equals` function from this module without having to write out\n`Claim.isEqual Debug.toString` every time.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrian-watkins%2Felm-spec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrian-watkins%2Felm-spec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrian-watkins%2Felm-spec/lists"}