{"id":13509255,"url":"https://github.com/derekkraan/walkman","last_synced_at":"2025-03-16T23:31:30.678Z","repository":{"id":48079243,"uuid":"163973803","full_name":"derekkraan/walkman","owner":"derekkraan","description":"Isolate tests from the real world, inspired by Ruby's VCR.","archived":false,"fork":false,"pushed_at":"2021-08-08T11:00:16.000Z","size":62,"stargazers_count":53,"open_issues_count":4,"forks_count":5,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-05-02T11:12:07.778Z","etag":null,"topics":["elixir","integration","testing"],"latest_commit_sha":null,"homepage":"","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/derekkraan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-01-03T13:02:30.000Z","updated_at":"2024-04-07T08:56:59.000Z","dependencies_parsed_at":"2022-08-12T18:10:30.073Z","dependency_job_id":null,"html_url":"https://github.com/derekkraan/walkman","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/derekkraan%2Fwalkman","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/derekkraan%2Fwalkman/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/derekkraan%2Fwalkman/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/derekkraan%2Fwalkman/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/derekkraan","download_url":"https://codeload.github.com/derekkraan/walkman/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243832627,"owners_count":20355120,"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":["elixir","integration","testing"],"created_at":"2024-08-01T02:01:05.285Z","updated_at":"2025-03-16T23:31:30.308Z","avatar_url":"https://github.com/derekkraan.png","language":"Elixir","funding_links":[],"categories":["Testing"],"sub_categories":[],"readme":"# Walkman\n\n[![Hex pm](http://img.shields.io/hexpm/v/walkman.svg?style=flat)](https://hex.pm/packages/walkman) [![CircleCI badge](https://circleci.com/gh/derekkraan/walkman.svg?style=svg\u0026circle-token=:circle-token)](https://circleci.com/gh/derekkraan/walkman)\n\nWalkman was inspired by Ruby's VCR. While VCR deals explicitely with HTTP requests, Walkman is useful for performing automated mocking of any module.\n\nWalkman wraps modules instead of modifying them directly, which means there is less funny business going on, so less chance newer versions of Elixir will break the package. Walkman is more explicit and less magical, and as a result you will have to write a tiny bit more boilerplate than you're maybe used to.\n\n## Getting started\n\nSomewhere in your application you've got a module, `MyModule`, that communicates with the outside world. Perhaps it is an SSH driver, or it makes an HTTP request.\n\nMake the location of this module configurable\n\n```elixir\n# config/config.exs\n\nconfig :my_app, my_module: MyModule\n```\n\n```elixir\n# config/test.exs\n\nconfig :my_app, my_module: MyModuleWrapper\n```\n\nReplace `MyModule` in your application with `Application.get_env(:my_app, :my_module)`.\n\nWrap `MyModule` with `MyModuleWrapper`.\n\n```elixir\n# test/support/my_module_wrapper.ex\n\nrequire Walkman\n\nWalkman.def_stub(MyModuleWrapper, for: MyModule)\n```\n\nLastly, in `mix.exs`, add `test/support/` to the paths that need to be compiled in `:test`.\n\n```elixir\ndef project do\n  [\n    # Everything that usually goes here\n    elixirc_paths: elixirc_paths(Mix.env())\n  ]\nend\n\ndefp elixirc_paths(:test), do: [\"lib\", \"test/support\"]\ndefp elixirc_paths(_), do: [\"lib\"]\n```\n\nNow you can use \"tapes\" in your tests.\n\n```elixir\ntest \"MyModule\" do\n  Walkman.use_tape \"my wrapper tape\" do\n    # test code that uses `MyModule` underwater\n  end\nend\n```\n\nAdd the fixtures that Walkman creates to your repository.\n\n## Generating fresh fixtures\n\nTo generate new fixtures, just remove the \"tapes\" you want to regenerate and re-run the tests. Like VCR, if Walkman doesn't find an existing fixture, it will create one.\n\n## Fixture file format\n\nFixtures are saved in Erlang's binary [External Term Format](http://erlang.org/doc/apps/erts/erl_ext_dist.html), which most editors won't be able to open correctly. If you want to see what exactly has been recorded, you can use `:erlang.binary_to_term()` to parse the file contents back into readable Elixir terms.\n\n```elixir\nFile.read!(\"path/to/fixture\") |\u003e :erlang.binary_to_term()\n```\n\n## Changing default tape mode\n\nBy default, all Walkman tapes are only available in the scope of the current process.\nTo make the tape available to other processes you have to set `global: true`:\n\n```elixir\ntest \"MyModule\" do\n  Walkman.use_tape \"my wrapper tape\", global: true do\n    # test code that uses `MyModule` underwater\n  end\nend\n```\n\nThe default behaviour can be changed in `config/test.exs`:\n\n`config :walkman, global: true`\n\n## Disabling module md5 checks\n\nBy default Walkman re-record tapes every time the wrapped module changes and this is done by storing the md5 of the module on the tape.\n\nTo change this behaviour the option `module_changes` should be set to `:ignore` or `:warn` which can be done per tape as in the example below:\n\n```elixir\ntest \"MyModule\" do\n  Walkman.use_tape \"my wrapper tape\", module_changes: :warn do\n    # test code that uses `MyModule` underwater\n  end\nend\n```\n\nThe module_changes option accepts the following values:\n- `:rerecord` - if the recorded module changes the tape is automatically re-recorded.\n- `:warn` - if the recorded module changes a warning is logged.\n- `:ignore` - It ignores any changes in the recorded module\n\nThe default behaviour can also be changed in `config/test.exs`:\n\n`config :walkman, module_changes: :ignore`\n\n## Running \"integration\" specs\n\nIf you set Walkman to `:integration` mode then it will pass all function calls through to the wrapped module (instead of using the fixtures).\n\n`Walkman.set_mode(:integration)`\n\n## Limitations\n\no Walkman cannot run specs in parallel. Walkman sets the \"tape\" globally and would have no way of knowing from which test a particular call originates.\n\n## Installation\n\nIf [available in Hex](https://hex.pm/docs/publish), the package can be installed\nby adding `walkman` to your list of dependencies in `mix.exs`:\n\n```elixir\ndef deps do\n  [\n    {:walkman, \"~\u003e 0.3.0\", only: :test}\n  ]\nend\n```\n\n## Contributing\n\nNote that if you want to run Walkman's tests locally, you'll need to be running Elixir v1.9.1 and Erlang v22.1.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fderekkraan%2Fwalkman","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fderekkraan%2Fwalkman","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fderekkraan%2Fwalkman/lists"}