{"id":13564473,"url":"https://github.com/randycoulman/mix_test_interactive","last_synced_at":"2025-12-30T10:20:25.976Z","repository":{"id":39020882,"uuid":"328272011","full_name":"randycoulman/mix_test_interactive","owner":"randycoulman","description":"Interactive watch mode for Elixir's mix test. https://hexdocs.pm/mix_test_interactive/","archived":false,"fork":false,"pushed_at":"2024-03-05T04:40:43.000Z","size":171,"stargazers_count":70,"open_issues_count":8,"forks_count":11,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-05-21T19:19:27.530Z","etag":null,"topics":["interactive","mix","mix-task","mix-test","watch"],"latest_commit_sha":null,"homepage":"","language":"Elixir","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/randycoulman.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","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":"2021-01-10T00:19:13.000Z","updated_at":"2024-05-19T20:19:16.000Z","dependencies_parsed_at":"2024-03-05T05:31:25.041Z","dependency_job_id":"4576629b-701a-4801-ae34-f19d62912ce2","html_url":"https://github.com/randycoulman/mix_test_interactive","commit_stats":{"total_commits":70,"total_committers":5,"mean_commits":14.0,"dds":0.0714285714285714,"last_synced_commit":"1547f664f49b8008beca3803e7f7ce5eadfbbdd0"},"previous_names":["influxdata/mix_test_interactive"],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/randycoulman%2Fmix_test_interactive","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/randycoulman%2Fmix_test_interactive/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/randycoulman%2Fmix_test_interactive/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/randycoulman%2Fmix_test_interactive/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/randycoulman","download_url":"https://codeload.github.com/randycoulman/mix_test_interactive/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247543591,"owners_count":20955865,"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":["interactive","mix","mix-task","mix-test","watch"],"created_at":"2024-08-01T13:01:31.910Z","updated_at":"2025-12-30T10:20:25.964Z","avatar_url":"https://github.com/randycoulman.png","language":"Elixir","funding_links":[],"categories":["Testing"],"sub_categories":[],"readme":"# mix test.interactive\n\n[![Build\nStatus](https://github.com/randycoulman/mix_test_interactive/actions/workflows/ci.yml/badge.svg)](https://github.com/randycoulman/mix_test_interactive/actions)\n[![Module\nVersion](https://img.shields.io/hexpm/v/mix_test_interactive.svg)](https://hex.pm/packages/mix_test_interactive)\n[![Hex\nDocs](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://hexdocs.pm/mix_test_interactive/)\n[![License](https://img.shields.io/hexpm/l/mix_test_interactive.svg)](https://github.com/randycoulman/mix_test_interactive/blob/master/LICENSE.md)\n\n`mix test.interactive` is an interactive test runner for ExUnit tests.\n\nBased on Louis Pilfold's wonderful\n[mix-test.watch](https://github.com/lpil/mix-test.watch) and inspired by Jest's\ninteractive watch mode, `mix test.interactive` allows you to dynamically change\nwhich tests should be run with a few keystrokes.\n\nIt allows you to easily switch between running all tests, stale tests, or failed\ntests. Or, you can run only the tests whose filenames contain a substring. You\ncan also control which tags are included or excluded, modify the maximum number\nof failures allowed, repeat the test suite until a failure occurs, specify the\ntest seed to use, and toggle tracing on and off. Includes an optional \"watch\nmode\" which runs tests after every file change.\n\n## Installation\n\n`mix test.interactive` can be added as a dependency to your project, or it can\nbe run from an Elixir script without being added to your project.\n\n### Installing as a Dependency\n\nTo install `mix test.interactive` as a dependency of your project, making it\navailable to anyone working in the project, add `mix_test_interactive` to the\nlist of dependencies in your project's `mix.exs` file:\n\n```elixir\ndef deps do\n  [\n    {:mix_test_interactive, \"~\u003e 5.1\", only: :dev, runtime: false}\n  ]\nend\n```\n\n### Running from an Elixir Script\n\nIf you are working on a 3rd-party project, you may not be able to add\n`mix test.interactive` as a dependency. In this case, it is possible\nto invoke `mix test.interactive` from an Elixir script.\n\nTo accomplish this, put the following script somewhere on your PATH and make it\nexecutable.\n\n```elixir\n#!/usr/bin/env elixir\n\nMix.install([\n  {:mix_test_interactive, \"~\u003e 4.1\"}\n])\n\nMixTestInteractive.run(System.argv())\n```\n\nAs an example, let's assume you've named the script `mti_exec`.\n\nNow you can `cd` to the project's root directory, and run `mti_exec`. The script\nwill accept all of `mix_test_interactive`'s [command-line options](#options) and\nallow you to use any of its [interactive commands](#interactive-commands).\n\n## Usage\n\n```shell\nmix test.interactive \u003coptions\u003e [-- \u003cmix test arguments\u003e]\nmix test.interactive \u003cmix test arguments\u003e\nmix test.interactive --help\nmix test.interactive --version\n```\n\nYour tests will run immediately (and every time a file changes).\n\n### Options\n\n`mix test.interactive` understands the following options, most of which\ncorrespond to configuration settings below.\n\nNote that, if you want to pass both mix test.interactive options and mix test\narguments, you must separate them with `--`.\n\nIf an option is provided on the command line, it will override the same option\nspecified in the configuration.\n\n- `--(no-)ansi-enabled`: Enable ANSI (colored) output when running tests\n  (default `false` on Windows; `true` on other platforms).\n- `--(no-)clear`: Clear the console before each run (default `false`).\n- `--command \u003ccommand\u003e [--arg \u003carg\u003e]`: Custom command and arguments for running\n  tests (default: \"mix\" with no arguments). NOTE: Use `--arg` multiple times to\n  specify more than one argument.\n- `--exclude \u003cregex\u003e`: Exclude files/directories from triggering test runs\n  (default: `[\"~r/\\.#/\", \"~r{priv/repo/migrations}\"`]) NOTE: Use `--exclude`\n  multiple times to specify more than one regex.\n- `--extra-extensions \u003cextension\u003e`: Watch files with additional extensions\n  (default: []).\n- `--runner \u003cmodule name\u003e`: Use a custom runner module (default:\n  `MixTestInteractive.PortRunner`).\n- `--task \u003ctask name\u003e`: Run a different mix task (default: `\"test\"`).\n- `--(no-)timestamp`: Display the current time before running the tests\n  (default: `false`).\n- `--(no-)verbose`: Display the command to be run before running the tests\n  (default: `false`).\n- `--(no-)watch`: Don't run tests when a file changes (default: `true`).\n\nAll of the `\u003cmix test arguments\u003e` are passed through to `mix test` on every test\nrun.\n\n`mix test.interactive` will detect the `--exclude`, `--failed`, `--include`,\n`--only`, `--seed`, and `--stale` options and use those as initial settings in\ninteractive mode. You can then use the interactive mode commands to adjust those\noptions as needed. It will also detect any filename or pattern arguments and use\nthose as initial settings. Note that if you specify a pattern on the\ncommand-line, `mix test.interactive` will find all test files matching that\npattern and pass those to `mix test` as if you had used the `p` command.\n\n### Patterns and filenames\n\n`mix test.interactive` can take the same filename or filename:line_number\npatterns that `mix test` understands. It also allows you to specify one or more\n\"patterns\" - strings that match one or more test files. When you provide one or\nmore patterns on the command-line, `mix test.interactive` will find all test\nfiles matching those patterns and pass them to `mix test` as if you had used the\n`p` command (described below).\n\n## Interactive Commands\n\nAfter the tests run, you can use the interactive commands to change which tests\nwill run.\n\n- `a`: Run all tests. Clears the `--failed` and `--stale` options as well as\n  any patterns.\n- `d \u003cseed\u003e`: Run the tests with a specific seed.\n- `d`: Clear any previously specified seed.\n- `f`: Run only tests that failed on the last run (equivalent to the\n  `--failed` option of `mix test`).\n- `i \u003ctags...\u003e`: Include tests tagged with the listed tags (equivalent to the\n  `--include` option of `mix test`).\n- `i`: Clear any included tags.\n- `m \u003cmax\u003e`: Specify the maximum number of failures allowed (equivalent to the\n  `--max-failures` option of `mix test`).\n- `m`: Clear any previously specified maximum number of failures.\n- `o \u003ctags...\u003e`: Run only tests tagged with the listed tags (equivalent to the\n  `--only` option of `mix test`).\n- `o`: Clear any \"only\" tags.\n- `p`: Run only test files that match one or more provided patterns. A pattern\n  is the project-root-relative path to a test file (with or without a line\n  number specification) or a string that matches a portion of full pathname.\n  e.g. `test/my_project/my_test.exs`, `test/my_project/my_test.exs:12:24` or\n  `my`.\n- `q`: Exit the program. (Can also use `Ctrl-D`.)\n- `r \u003ccount\u003e`: (Elixir 1.17.0 and later) Run tests up to \u003ccount\u003e times until a\n  failure occurs (equivalent to the `--repeat-until-failure` option of `mix\ntest`).\n- `r`: (Elixir 1.17.0 and later) Clear the \"repeat-until-failure\" count.\n- `s`: Run only test files that reference modules that have changed since the\n  last run (equivalent to the `--stale` option of `mix test`).\n- `t`: Turn test tracing on or off (equivalent to the `--trace` option of `mix\ntest`).\n- `x \u003ctags...\u003e`: Exclude tests tagged with the listed tags (equivalent to the\n  `--exclude` option of `mix test`).\n- `x`: Clear any excluded tags.\n- `w`: Turn file-watching mode on or off.\n- `Enter`: Re-run the current set of tests without requiring a file change.\n- `?`: Show usage help.\n\n## Configuration\n\n`mix test.interactive` can be configured with various options using application\nconfiguration. You can also use command line arguments to specify these\nconfiguration options, or to override configured options.\n\n### `ansi_enabled`: Enable ANSI (colored) output when running tests\n\nWhen `ansi_enabled` is set to true, `mix test.interactive` will enable ANSI\noutput when running tests, allowing for `mix test`'s normal colored output.\n\n```elixir\n# config/config.exs\nimport Config\n\nif Mix.env == :dev do\n  config :mix_test_interactive,\n    ansi_enabled: false\nend\n```\n\nThe default is `false` on Windows and `true` on other platforms.\n\n### `clear`: Clear the console before each run\n\nIf you want `mix test.interactive` to clear the console before each run, you can\nenable this option in your config/dev.exs as follows:\n\n```elixir\n# config/config.exs\nimport Config\n\nif Mix.env == :dev do\n  config :mix_test_interactive,\n    clear: true\nend\n```\n\n### `command`: Use a custom command\n\nBy default, `mix test.interactive` uses `mix test` to run tests.\n\nYou might want to provide a custom command that does other things before or\nafter running `mix`. In that case, you can customize the command used for\nrunning tests.\n\nFor example, you might want to provide a name for the test runner process to\nallow connection from other Erlang nodes. Or you might want to run other\ncommands before or after running the tests.\n\nIn those cases, you can customize the command that `mix test.interactive` will\nuse to run your tests. `mix test.interactive` assumes that the custom command\nultimately runs `mix` under the hood (or at least accepts all of the same\ncommand-line arguments as `mix`). The custom command can either be a string or a\n`{command, [..args..]}` tuple.\n\nExamples:\n\n```elixir\n# config/config.exs\nimport Config\n\nif Mix.env == :dev do\n  config :mix_test_interactive,\n    command: \"path/to/my/test_runner.sh\"\nend\n```\n\n```elixir\n# config/config.exs\nimport Config\n\nif Mix.env == :dev do\n  config :mix_test_interactive,\n    command: {\"elixir\", [\"--sname\", \"name\", \"-S\", \"mix\"]}\nend\n```\n\nTo run a different mix task instead, see the `task` option below.\n\n### `exclude`: Excluding files or directories\n\nTo stop changes to specific files or directories from triggering test runs, you\ncan add `exclude:` regexp patterns to your config in `mix.exs`:\n\n```elixir\n# config/config.exs\nimport Config\n\nif Mix.env == :dev do\n  config :mix_test_interactive,\n    exclude: [~r/db_migration\\/.*/,\n              ~r/useless_.*\\.exs/]\nend\n```\n\nThe default is `exclude: [~r/\\.#/, ~r{priv/repo/migrations}]`.\n\n### `extra_extensions`: Watch files with additional extensions\n\nBy default, `mix test.interactive` will trigger a test run when a known Elixir\nor Erlang file has changed, but not when any other file changes.\n\nYou can specify additional file extensions to be included with the\n`extra_extensions` option.\n\n```elixir\n# config/config.exs\nimport Config\n\nif Mix.env == :dev do\n  config :mix_test_interactive,\n    extra_extensions: [\"json\"]\nend\n```\n\n`mix test.interactive` always watches files with the following extensions:\n`.erl`, `.ex`, `.exs`, `.eex`, `.leex`, `.heex`, `.xrl`, `.yrl`, and `.hrl`. To\nignore files with any of these extensions, you can specify an `exclude` regexp\n(see above).\n\n### `runner`: Use a custom runner module\n\nBy default `mix test.interactive` uses an internal module named\n`MixTestInteractive.PortRunner` to run the tests. If you want to run the tests\nin a different way, you can supply your own runner module instead. Your module\nmust implement the `MixTestInteractive.TestRunner` behaviour, either implicitly\nor explicitly.\n\n```elixir\n# config/config.exs\nimport Config\n\nif Mix.env == :dev do\n  config :mix_test_interactive,\n    runner: MyApp.FancyTestRunner\nend\n```\n\n### `task`: Run a different mix task\n\nBy default, `mix test.interactive` runs `mix test`.\n\nThrough the mix config it is possible to run a different mix task. `mix\ntest.interactive` assumes that this alternative task accepts the same\ncommand-line arguments as `mix test`.\n\n```elixir\n# config/config.exs\nimport Config\n\nif Mix.env == :dev do\n  config :mix_test_interactive,\n    task: \"custom_test_task\"\nend\n```\n\nThe task is run with `MIX_ENV` set to `test`.\n\nTo use a custom command instead, see the `command` option above.\n\n### `timestamp`: Display the current time before running the tests\n\nWhen `timestamp` is set to true, `mix test.interactive` will display the current\ntime (UTC) just before running the tests.\n\n```elixir\n# config/config.exs\nimport Config\n\nif Mix.env == :dev do\n  config :mix_test_interactive,\n    timestamp: true\nend\n```\n\n### `verbose`: Display the command to be run before running the tests\n\nWhen `verbose` is set to true, `mix test.interactive` will display the command\nline it is about to execute just before running the tests.\n\n```elixir\n# config/config.exs\nimport Config\n\nif Mix.env == :dev do\n  config :mix_test_interactive,\n    verbose: true\nend\n```\n\n## Compatibility Notes\n\nOn Linux you may need to install `inotify-tools`.\n\n## Desktop Notifications\n\nYou can enable desktop notifications with\n[ex_unit_notifier](https://github.com/navinpeiris/ex_unit_notifier).\n\n## Acknowledgements\n\nThis project started as a clone of the wonderful\n[mix-test.watch](https://github.com/lpil/mix-test.watch) project, which I've\nused and loved for years. I've added the interactive mode features to the\nexisting feature set.\n\nThe idea for having an interactive mode comes from [Jest](https://jestjs.io/)\nand its incredibly useful interactive watch mode.\n\n## Copyright and License\n\nCopyright (c) 2021-2024 Randy Coulman\n\nThis work is free. You can redistribute it and/or modify it under the terms of\nthe MIT License. See the [LICENSE.md](./LICENSE.md) file for more details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frandycoulman%2Fmix_test_interactive","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frandycoulman%2Fmix_test_interactive","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frandycoulman%2Fmix_test_interactive/lists"}