WriteThemFirst/approvals-java

# Frequently Asked Questions

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->


- [How to ensure IntelliJ is not creating empty lines in approved files?](#how-to-ensure-intellij-is-not-creating-empty-lines-in-approved-files)
- [How to commit properly approved files in Git?](#how-to-commit-properly-approved-files-in-git)
- [How to use Approvals-Java with another JVM language?](#how-to-use-approvals-java-with-another-jvm-language)
  - [Example solution with ScalaTest](#example-solution-with-scalatest)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

## How can I use a different tool to approve the differences ?

Since [v0.9.0](https://github.com/WriteThemFirst/approvals-java/releases/tag/v0.9.0) 
a configuration file is generated on first test in `~/.approvals-java`.
It contains all detected supported tools, you can select your favorite one by uncommenting it.

Alternatively, you can provide your own tool using this syntax: 

    # complete path /// arguments using reserved keywords %received% %approved%
    
### Windows example

    C:\Program Files\JetBrains\IntelliJ IDEA Community Edition 2019.1.1\bin\idea64.exe //// diff %received% %approved%

### Mac or linux example

    /usr/local/bin/idea.sh //// diff %received% %approved%

### Rubymine support

If you are doing JRuby developpement with Rubymine, you can use [RubyMine integrated diff tool]( https://www.jetbrains.com/help/ruby/command-line-differences-viewer.html) to approve the differences.

1. Create the diff script with https://www.jetbrains.com/help/ruby/working-with-the-ide-features-from-command-line.html#launchers-macos-linux
2. Update `~/.approvals-java` similar to IntelliJ : 

       /usr/local/bin/mine //// diff %received% %approved%


## How to ensure IntelliJ is not creating empty lines in approved files? 

**Problem:** When using the default `Windows.IDEA` Reporter, an empty line is added at the end of the *approved* file and the tests never pass.

**Solution:** Add this block to your `.editorconfig` file: 

```
[*.approved]
insert_final_newline = false
```

Or, if you don't use *editorconfig*, check your IDE's formatter settings.

## How to commit properly approved files in Git? 

**Fact:** The `*.approved` files must be checked into source your source control since they are part of your tests. 

**Problem:** You could encounter issues with Git messing with line endings so the file always looks like being modified while running the tests.

**Solution:** Add this block to your `.gitattributes`:

```
*.approved.* binary
*.approved binary
```

Git will then treat the *approved* files as *binary* instead of *text* and will respect their line endings.

## How to handle differences in line-endings

Make sure the received file (produced by your software) has the same line-endings that the *approved* file
generated by your merge tool. Especially when you commit these files, beware of git configurations like `autocrlf`. 
See [this post](https://stackoverflow.com/questions/35503036/git-and-intellij-lines-separator-issue) 
for details.

## How can I approve a lot of changes after a big change in my code ?

Since [v0.8.0](https://github.com/WriteThemFirst/approvals-java/releases/tag/v0.8.0) you can
set the system property "AUTO_APPROVE". This will make the approbation library trust all
content passed to `verify` methods.

You might want to clean your previous *approved* files before with something like 
`find . -name "*.approved" | xargs rm -rf` (BE CAREFUL).

## How to use Approvals-Java with another JVM language? 

**Fact:** Approvals tries to name your *approved* files by looking at the stack 
which called `Approvals.verify()` to detect the calling class and method name.

**Problem:** When you use it from a Kotlin or Scala unit test framework, you could have issues with the naming.

### Example solution with ScalaTest

When you use `Approvals.verify()` from a spec, you need to specify the filename for *approved* and *received* files because it is not inferred from the stack like in JUnit tests (the classes and methods are not expressive in this context).

```scala
 "Parser" should "parse example" in {
    val problem = myParser.parse(data)
    approvals.verify(problem, "parsedExample")
  }
```

You can define a trait `Approbation` like this:

```scala
import com.github.writethemfirst.approvals.Approvals

trait Approbation {
  val approvals = new Approvals()
}
```