Update Readme

AlexB52 · Dec 11, 2024 · 190bb8d · 190bb8d
1 parent 9ebece2
commit 190bb8d
Showing 1 changed file with 44 additions and 76 deletions.
diff --git a/README.md b/README.md
@@ -1,16 +1,15 @@
 [![Gem Version](https://badge.fury.io/rb/retest.svg)](https://badge.fury.io/rb/retest)
 
-### Retest 2.0 is now available as a pre-release! You can try it out with `gem install retest --pre`.
+### Retest 2.0 is now available!
 
 Feedback is welcome in this [Discussion - Retest V2.0 - Interactive Panel (proof of concept)](https://github.com/AlexB52/retest/discussions/216)
 
 # Retest
 
-Retest is a small command-line tool to help you refactor code by watching a file change and running its matching spec. Designed to be dev-centric and project independent, it can be used on the fly. No Gemfile updates, no commits to a repo or configuration files required to start refactoring. Works with every Ruby projects (at least that is the end goal)
+A trusty CLI companion to monitor file changes and automatically run the corresponding Ruby specs. Ready to assist on any Ruby project, no setup needed! Designed to be dev-centric and project independent, it can be used on the fly. No Gemfile updates, no commits to a repo or configuration files required to start refactoring. Works with every Ruby projects (at least that is the end goal)
 
 ## Demo
 
-
 https://user-images.githubusercontent.com/7149034/153734043-1d136f27-5c24-4676-868b-0fde76016b13.mp4
 
 ## Installation
@@ -19,84 +18,72 @@ Install it on your machine without adding it on a Gemfile:
 
     $ gem install retest
 
-## Usage
-
-Retest is used in your terminal after accessing your ruby project folder.
-
-### Help
-
-Find out what retest can do anytime with
-
-    $ retest -h
-
-### For Refactoring
-
-#### 1. Run a hardcoded command
-
-This the most simple usage of retest: running the same command over and over after each file update.
-
-Example:
+## Ruby Support
 
-    $ retest 'bundle exec rspec spec/features/posts_spec.rb'
+Retest supports ruby 2.5 and above.
 
-In this example, the feature spec `spec/features/posts_spec.rb` will be tested after any ruby file is updated.
+## Watching tools: Watchexec & Listen
 
-#### 2. Run a dynamic command with placeholders
+By default retest ships with [Listen](https://github.com/guard/listen) which is used to listen to file changes. 
 
-Retest provides few placeholders to help you run a command after every file change. The placeholders can be used on their own or together.
+Retest will use [watchexec](https://github.com/watchexec/watchexec) a more performant file watcher when installed on the matchine. watchexec will only work with a version >= 2.2.0
 
-1. `<test>` placeholder 
+To force the usage of a watcher you can use the `-w` option as `retest -w watchexec`
 
-You can use the placeholder `<test>` to tell the gem where to put the test file path in your command. When a file is changed, the gem will find its matching test and run the test command with it.
+## Usage
 
-Example:
+Retest is used in your terminal after accessing your ruby project folder.
 
-    $ retest 'bin/rails test <test>'
-
-In this example, if `app/models/post.rb` is changed then retest will run `bin/rails test test/models/post_test.rb`
-
-2. `<changed>` placeholder
-
-You can use the placeholder `<changed>` to tell the gem where to put the changed file path in your command. When a file is changed, the gem will run the command with it.
+### Help
 
-Example:
+Find out what retest can do anytime with
 
-    $ retest 'rubocop <changed>'
-
-In this example, if `app/models/post.rb` is changed then retest will run `rubocop app/models/post.rb`  
+    $ retest -h
 
-#### 3. Run a dynamic command with shortcuts
+Here is a quick summary:
 
-Few shortcut flags exist to avoid writing the full test command.
+  * run a hardcoded command: `retest 'bin/rails test test/models/post_test.rb'`
+  * use placeholders: `retest 'bin/rails test <test> && rubocop <changed>`
+  * play a sound for feedback: `retest --notify`
+  * run all specs when a file change: `retest --all`
+  * run all matching specs from a diffed branch: `retest --diff origin/main`
 
-    $ retest --rspec
-    $ retest --rails
-    $ retest --rake --all
+### Interactive companion
 
-#### 4. Let retest figure it all out
+An interactive shell will start when launching retest to help your testing workflow. Enter 'h' to see all the options.
 
-Let retest find your ruby setup and run the appropriate command using:
+```
+Setup identified: [RAKE]. Using command: 'bundle exec rake test TEST=<test>'
+Watcher: [WATCHEXEC]
+Launching Retest...
+Ready to refactor! You can make file changes now
+
+Type interactive command and press enter. Enter 'h' for help.
+> h
+
+* 'h', 'help'              # Prints help.
+* 'p', 'pause'             # Pauses Retest. Tests aren't run on file change events until unpaused.
+* 'u', 'unpause'           # Unpauses Retest.
+* <ENTER>                  # Runs last changed triggered command.
+* 'ra, 'run all'           # Runs all tests.
+* 'f', 'force'             # Forces a selection of test to run on every file change.
+* 'r', 'reset'             # Disables forced selection.
+* 'd', 'diff' [GIT BRANCH] # Runs matching specs that changed from a target branch.
+* 'c'                      # Clears window.
+* 'e', 'exit'              # Exits Retest.
 
-    $ retest
-    $ retest --all
+```
+### Running rules
 
-#### Running rules
+When on a forced selection, retest will run the forced selection regardless of the file changed.
 
-The gem works as follows:
+Otherwise, the gem works as follows:
 
 * When a **ruby file** is changed, retest will run its matching test.
 * When a **test file** is changed, retest will run the test file.
 * When multiple matching test files are found, retest asks you to confirm the file and save the answer.
 * When a test file is not found, retest runs the last run command or throw a 404.
 
-### Pull request scans
-
-You can diff a branch and test all the relevant test files before pushing your branch and trigger a full CI suite. 
-
-    $ retest --diff origin/main
-
-In this example, retest lists all the files changed between `HEAD` and `origin/main`, finds all the relevant tests and only run those.
-
 ## Why?
 It is advised to be one `cmd + z` away from green tests when refactoring. This means running tests after every line change. Let Retest rerun your tests after every file change you make.
 
@@ -121,25 +108,6 @@ $ retest 'bundle exec rails test <test>'
 * If an error comes in try using `bundle exec` like so: `$ retest 'bundle exec rake test <test>'`
 * Aliases saved on ~/.bashrc or ~/.zshrc cannot be run that way with the `retest` command
 
-## Ruby Support
-
-Retest supports ruby 2.5 and above.
-
-## Roadmap
-
-- [x] MVP
-- [x] When multiple test files are found, ask which file to run and save the answer.
-- [x] When a test file is not found run the last command again.
-- [x] Run within Docker.
-- [x] Handle main Ruby setups
-  - [x] Bundler Gem
-  - [x] Rails
-  - [x] Ad-hoc scripts
-  - [x] Hanami
-- [ ] Handle other languages: Go, Elixir, Node, Python, PHP
-  - [ ] Go (project started)
-- [ ] Aliases from oh-my-zsh and bash profiles?
-
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.