Merge pull request #193 from ruby-syntax-tree/silent-tests

Make the test suite silent

Author: kddnewton

README.md

@@ -46,8 +46,8 @@ It is built with only standard library dependencies. It additionally ships with
   - [textDocument/formatting](#textdocumentformatting)
   - [textDocument/inlayHint](#textdocumentinlayhint)
   - [syntaxTree/visualizing](#syntaxtreevisualizing)
-- [Plugins](#plugins)
-  - [Customization](#customization)
+- [Customization](#customization)
+  - [Plugins](#plugins)
   - [Languages](#languages)
 - [Integration](#integration)
   - [Rake](#rake)
@@ -320,6 +320,10 @@ Baked into this syntax is the ability to provide exceptions to file name pattern
 stree write "**/{[!schema]*,*}.rb"
 ```
 
+## Formatting
+
+
+
 ## Library
 
 Syntax Tree can be used as a library to access the syntax tree underlying Ruby source code.
@@ -619,18 +623,45 @@ Implicity, the `2 * 3` is going to be executed first because the `*` operator ha
 
 The language server additionally includes this custom request to return a textual representation of the syntax tree underlying the source code of a file. Language server clients can use this to (for example) open an additional tab with this information displayed.
 
-## Plugins
+## Customization
+
+There are multiple ways to customize Syntax Tree's behavior when parsing and formatting code. You can ignore certain sections of the source code, you can register plugins to provide custom formatting behavior, and you can register additional languages to be parsed and formatted.
+
+### Ignoring code
+
+To ignore a section of source code, you can a special `# stree-ignore` comment. This comment should be placed immediately above the code that you want to ignore. For example:
+
+```ruby
+numbers = [
+  10000,
+  20000,
+  30000
+]
+```
+
+Normally the snippet above would be formatted as `numbers = [10_000, 20_000, 30_000]`. However, sometimes you want to keep the original formatting to improve readability or maintainability. In that case, you can put the ignore comment before it, as in:
+
+```ruby
+# stree-ignore
+numbers = [
+  10000,
+  20000,
+  30000
+]
+```
+
+Now when Syntax Tree goes to format that code, it will copy the source code exactly as it is, including the newlines and indentation.
 
-You can register additional customization and additional languages that can flow through the same CLI with Syntax Tree's plugin system. When invoking the CLI, you pass through the list of plugins with the `--plugins` options to the commands that accept them. They should be a comma-delimited list. When the CLI first starts, it will require the files corresponding to those names.
+### Plugins
 
-### Customization
+You can register additional customization that can flow through the same CLI with Syntax Tree's plugin system. When invoking the CLI, you pass through the list of plugins with the `--plugins` options to the commands that accept them. They should be a comma-delimited list. When the CLI first starts, it will require the files corresponding to those names.
 
-To register additional customization, define a file somewhere in your load path named `syntax_tree/my_plugin`. Then when invoking the CLI, you will pass `--plugins=my_plugin`. To require multiple, separate them by a comma. In this way, you can modify Syntax Tree however you would like. Some plugins ship with Syntax Tree itself. They are:
+To register plugins, define a file somewhere in your load path named `syntax_tree/my_plugin`. Then when invoking the CLI, you will pass `--plugins=my_plugin`. To require multiple, separate them by a comma. In this way, you can modify Syntax Tree however you would like. Some plugins ship with Syntax Tree itself. They are:
 
 * `plugin/single_quotes` - This will change all of your string literals to use single quotes instead of the default double quotes.
 * `plugin/trailing_comma` - This will put trailing commas into multiline array literals, hash literals, and method calls that can support trailing commas.
 
-If you're using Syntax Tree as a library, you should require those files directly.
+If you're using Syntax Tree as a library, you can require those files directly or manually pass those options to the formatter initializer through the `SyntaxTree::Formatter::Options` class.
 
 ### Languages
 

test/ractor_test.rb

@@ -20,18 +20,33 @@ def test_formatting
           source = SyntaxTree.read(filepath)
           program = SyntaxTree.parse(source)
 
-          Ractor.new(source, program, name: filepath) do |source, program|
-            SyntaxTree::Formatter.format(source, program)
+          with_silenced_warnings do
+            Ractor.new(source, program, name: filepath) do |source, program|
+              SyntaxTree::Formatter.format(source, program)
+            end
           end
         end
 
-      ractors.each(&:take)
+      ractors.each { |ractor| assert_kind_of String, ractor.take }
     end
 
     private
 
     def filepaths
       Dir.glob(File.expand_path("../lib/syntax_tree/{node,parser}.rb", __dir__))
     end
+
+    # Ractors still warn about usage, so I'm disabling that warning here just to
+    # have clean test output.
+    def with_silenced_warnings
+      previous = $VERBOSE
+
+      begin
+        $VERBOSE = nil
+        yield
+      ensure
+        $VERBOSE = previous
+      end
+    end
   end
 end

test/rake_test.rb

@@ -46,12 +46,11 @@ def invoke(task_name)
         invocation = nil
         stub = ->(args) { invocation = Invocation.new(args) }
 
-        begin
+        assert_raises SystemExit do
           SyntaxTree::CLI.stub(:run, stub) { ::Rake::Task[task_name].invoke }
-          flunk
-        rescue SystemExit
-          invocation
         end
+
+        invocation
       end
     end
   end