{"id":13509190,"url":"https://github.com/wesovilabs/exkorpion","last_synced_at":"2025-05-05T10:31:12.756Z","repository":{"id":62429197,"uuid":"66500710","full_name":"wesovilabs/exkorpion","owner":"wesovilabs","description":"A BDD library  for Elixir developers","archived":false,"fork":false,"pushed_at":"2018-05-08T05:14:17.000Z","size":84612,"stargazers_count":30,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"develop","last_synced_at":"2025-04-29T02:20:05.921Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wesovilabs.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}},"created_at":"2016-08-24T21:24:51.000Z","updated_at":"2024-01-04T16:07:07.000Z","dependencies_parsed_at":"2022-11-01T20:07:20.658Z","dependency_job_id":null,"html_url":"https://github.com/wesovilabs/exkorpion","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wesovilabs%2Fexkorpion","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wesovilabs%2Fexkorpion/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wesovilabs%2Fexkorpion/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wesovilabs%2Fexkorpion/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wesovilabs","download_url":"https://codeload.github.com/wesovilabs/exkorpion/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252480417,"owners_count":21754773,"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":[],"created_at":"2024-08-01T02:01:04.327Z","updated_at":"2025-05-05T10:31:12.406Z","avatar_url":"https://github.com/wesovilabs.png","language":"Elixir","funding_links":[],"categories":["Testing"],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.org/wesovilabs/exkorpion.png)](https://travis-ci.org/wesovilabs/exkorpion)\n[![Hex version](https://img.shields.io/hexpm/v/exkorpion.svg \"Hex version\")](https://hex.pm/packages/exkorpion)\n![Hex downloads](https://img.shields.io/hexpm/dt/exkorpion.svg \"Hex downloads\")\n\n# Exkorpion\n\n**An Elixir framework to do testing in a BDD way**\n\n## Installation\n\nLibrary is [available in Hex](http://hexdocs.pm/exkorpion), the package can be installed as:\n\n  1. Add `exkorpion` to your list of dependencies in `mix.exs`:\n\n    ```elixir\n    def deps do\n      [{:exkorpion, \"~\u003e 0.0.3\"}]\n    end\n    ```\n\n\nIn case of you don't have a elixir environment ready to code, please have a look at the below links:\n\n  - [Elixir installation](http://elixir-lang.org/install.html)\n  - [Mix introduction](http://elixir-lang.org/getting-started/mix-otp/introduction-to-mix.html)\n  - [Mix dependencies](https://hex.pm/docs/usage)\n\n\n## Exkorpion goals\n\n  - It wraps ExUnit and enhances their features providing developers with a BDD syntax. \n\n  - It helps us to write tests wasy-to-read.\n\n  - It is completely compatible with ExUnit.\n\n  - It force us to structure our tests in steps (given-when-then)\n\n  - It is based on a functional syntax, organization our tests steps by anonymous functions.\n\n  - It is not coupled to any other framework.\n\n\n## Getting started\n\n\n### Exkorpion syntax\n\nAs was mentioned on the above Exkorpion is mainly oriented to a bdd syntax:\n\n**scenario**:  A scenario groups multiple cases that test a functionality works as expected. By using scenario we achieve the below:\n\n  - Better documentation for other developers.\n  - Test are better organized and structured\n  - Working under an agile methodology we can match scenarios to acceptance criteria\n\n**it**: Exkorpion provide with a reserved word It to represent any of the cases inside a scenario.\n\n\n\n  ```elixir\n\n      scenario \"testing sum operation works as expected\" do\n\n         it \"sum positive numbers works as expected\" do\n\n         end\n\n         it \"sum negative numbers and it should work as expected\" do\n\n         end\n\n      end\n  ```\n\n\n**with/given/when/then**: These word are the ones that provide us with s BDD syntax. Actually even when we write some unit tests we should thinkg about them.\n\n  - *Given*: It defines the input data for performing the tests. (It's an optional step, it could be not neccessary sometimes)\n  - *When*:  It performs the action to be tested.\n  - *Then*:  It ensures the result in the preoviuos step are the expected.\n\n\n  ```elixir\n\n    it \"Ensures that get tracks service returns always 2 elements\" do\n      %{\n        when: fn _ -\u003e\n          %{result: build_conn() |\u003e get(\"/tracks\", \"v1\") |\u003e json_response |\u003e Poison.decode! }\n        end,  \n        then: fn ctx -\u003e\n          assert 2 === length(ctx.result)\n        end   \n      }\n    end\n  ```\n\n  we could make us of *with** step if we pretend to run the some tests for multiple input\n\n\n  ```elixir\n\n    it \"Ensures that add new track service works as expected\" do\n      %{\n        with: fn ctx -\u003e\n            [\n              %{new_track: %{\"title\" =\u003e \"Runaway\", \"singer\" =\u003e \"John Bon Jovi\"}},\n              %{new_track: %{\"title\" =\u003e \"Let her go\", \"singer\" =\u003e \"The passenger\"}},\n            ]\n        end,\n        given: \u0026(%{new_track_json: \u00261.new_track |\u003e Poison.encode!, previous_tracks: build_conn() |\u003e get(\"/tracks\", \"v1\") |\u003e json_response |\u003e Poison.decode! }),\n        when: fn ctx -\u003e\n          %{result: build_conn() |\u003e put_body_or_params(ctx.new_track) |\u003e post(\"/tracks\", \"v1\") |\u003e json_response |\u003e Poison.decode! }         \n\n        end,  \n          then: fn ctx -\u003e\n            assert length(ctx.previous_tracks)+1 === length(ctx.result)\n            assert true === Enum.member?(ctx.result, ctx.new_track)\n          end   \n      }\n    end\n  ```\n\n**before_each**: Before each will be inside of a scenario and provices with a reusable set of data for our tests.\n\n  ```elixir\n\n    scenario \"testing sum operation works as expected\" do\n    \n      before_each do\n        %{a: 10}\n      end\n\n      it \"sum positive numbers works as expected\" do\n        %{\n          given: \u0026(%{a: \u00261.a, b: 3}),\n          when: \u0026(%{c: \u00261.a + \u00261.b}),\n          then: fn ctx -\u003e\n            assert ctx.c === 13\n          end\n        }\n      end\n\n      it \"sum negative numbers and it should work as expected\" do\n        %{\n          given: \u0026(%{a: \u00261.a, b: -2}),\n          when: \u0026(%{c: sum(\u00261.a ,\u00261.b)}),\n          then: fn ctx -\u003e\n            assert ctx.c === 8\n          end\n        }\n      end\n\n    end\n  ```\n\n\n### First steps\n\n  - Once we have added exkorpion dependency to our test we can run the below command. This will creae a **scenario** directory on our poejct with a file named **scenario_helper.exs**.\n\n    ```elixir\n\n      mix exkorpion.init\n    ```\n\n  - By default **Exkorpion** will search files ended by \"**.._scenario.exs**\" inside directory scenarios. This could be easyly customized (We explain in following articles.)\n\n  - We can write one or more scenarios per file\n\n  - To run the exkorpion scenarios we just need to run\n\n    ```elixir\n\n      MIX_ENV=test mix exkorpion\n    ```\n  - Exkorpion provides with a friendly resume about our tests execution.\n  \n  **Success execution**\n  ![exkorpion success](https://github.com/wesovilabs/exkorpion/blob/master/images/scenario-success.png)\n\n\n  **Something went wrong!**\n  ![exkorpion error](https://github.com/wesovilabs/exkorpion/blob/master/images/scenario-error.png)   \n\n### Samples\n\n  It's highly recommendable you to have a look at some samples already developed: \n\n  - [Exkorpion project](https://github.com/wesovilabs/exkorpion/tree/develop/scenarios)\n  - [Maru training](https://github.com/wesovilabs/elixir_maru_training)\n\n\n## Contributors\n\n- **Iván Corrales Solera** :  You could reach me by , [email](mailto:developer@wesovilabs.com), [twitter](https://www.twitter.com/wesovilabs) or [Linkedin](www.linkedin.com/in/ivan-corrales-solera)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwesovilabs%2Fexkorpion","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwesovilabs%2Fexkorpion","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwesovilabs%2Fexkorpion/lists"}