From 190bb8dfa2d97bb392421397a1366052eca1a2f1 Mon Sep 17 00:00:00 2001 From: Alexandre Barret Date: Wed, 11 Dec 2024 22:01:35 +1300 Subject: [PATCH] Update Readme --- README.md | 120 ++++++++++++++++++++---------------------------------- 1 file changed, 44 insertions(+), 76 deletions(-) diff --git a/README.md b/README.md index 41feb0dc..f2a4e537 100644 --- 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. `` placeholder +To force the usage of a watcher you can use the `-w` option as `retest -w watchexec` -You can use the placeholder `` 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 ' - -In this example, if `app/models/post.rb` is changed then retest will run `bin/rails test test/models/post_test.rb` - -2. `` placeholder - -You can use the placeholder `` 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 ' - -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 && rubocop ` + * 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=' +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. +* # 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 ' * If an error comes in try using `bundle exec` like so: `$ retest 'bundle exec rake 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.