Missing Documentation Pages

[ScottBob]

Is there a documentation page that you would like to see?

Add the title of the page below in a comment. Also, please preference it with one of the following four categories:

1. Tutorial - Step-by-step guide to get started
2. How To - Recipe to solve a specific problem
3. Explanation - Theory and history around ApprovalTests
4. Reference - Description, lists, and statistics of ApprovalTests api

[Kurru]

1 or 2
https://github.com/approvals/ApprovalTests.Java/blob/master/approvaltests/docs/Reporters.md#class-and-method-level

I found the documentation about the PackageSettings a little lacking. Specifically I had a hard time figuring out the best configuration for use with IntelliJ running my tests. The differences between the various reporters were unclear and I had to try a bunch.

Separately, using PascalCase for variable names seems unusual vs camelCase or even better UPPER_SNAKE_CASE.

For the record, we eventually found:

public class PackageSettings {
  public static EnvironmentAwareReporter FrontloadedReporter = new JunitReporter();
  public static ApprovalFailureReporter UseReporter = new QuietReporter();
  public static String UseApprovalSubdirectory = "golden_files";
}

[Kurru]

https://github.com/approvals/ApprovalTests.Java/blob/master/approvaltests/docs/README.md

"Main concepts for ApprovalTests"
This section doesnt provide links to "writers" or "namers" which are otherwise mysterious for the user. Ideally there would be a link to explain these further and provide examples or customization options

[ScottBob]

@Kurru

I found the documentation about the PackageSettings a little lacking.

We created this page: https://github.com/approvals/ApprovalTests.Java/blob/master/approvaltests/docs/explanations/BestConfigurationPractices.md

Does it help?

[Kurru]

@ScottBob while that does help explain the order of reporters (and that you could have class or method level reporters) my comment was more about how I learned about how I needed to configure ApprovalTest to make it do what I wanted.

It took rather a long time to find that PackageSettings was the way to configure multiple test files in 1 consistent way.

Some difficulties I had after I figured out that PackageSettings was a thing included:

• what are the common parameters available in PackageSettings (though seems more accessible now)
• what is a "FrontloadedReporter" vs a "UseReporter" (still have no idea)
• why do I need a reporter? (to display the diffs it seems?)
• What the benefits between the reporters? (are they mostly just different diff tool integrations)
• I also dont know why someone would want to change a reporter for a class or a method. What are the common use-cases for this feature?

[ScottBob]

@Kurru We made a page about FrontLoadedReporters. Would appreciate feedback.

[ScottBob]

@Kurru We made a page about the benefits of different reporters. Would appreciate feedback.

[patkujawa-wf]

There's probably a reason it was deleted, but FYI https://github.com/approvals/ApprovalTests.Java/blob/a2867dbd6df17710d9cdfe5e9e100124bcd5ccf4/approvaltests/docs/explanations/BenefitsOfDifferentReporters.md no longer exists (https://github.com/approvals/ApprovalTests.Java/blob/master/approvaltests/docs/explanations/BenefitsOfDifferentReporters.md or elsewhere). It's still linked to/referenced from a few areas, though - https://github.com/search?q=repo%3Aapprovals%2FApprovalTests.Java%20BenefitsOfDifferentReporters&type=code

[ScottBob]

There's probably a reason it was deleted, but FYI https://github.com/approvals/ApprovalTests.Java/blob/a2867dbd6df17710d9cdfe5e9e100124bcd5ccf4/approvaltests/docs/explanations/BenefitsOfDifferentReporters.md no longer exists (https://github.com/approvals/ApprovalTests.Java/blob/master/approvaltests/docs/explanations/BenefitsOfDifferentReporters.md or elsewhere). It's still linked to/referenced from a few areas, though - https://github.com/search?q=repo%3Aapprovals%2FApprovalTests.Java%20BenefitsOfDifferentReporters&type=code

Thanks! We got rid of the broken links.

[ibanFR]

Hi everyone 👋

I’m new to ApprovalTests and was trying to set up my development environment using the Java starter project:
https://github.com/approvals/approvaltests.java.starterproject

As part of the setup, I deleted SampleTests.testWithApprovalTests.approved.txt and then ran the SampleTest class. I was expecting a diff tool to pop up, but nothing happened.

The instructions in the README.md mention that a diff tool is required, and for macOS the suggested option is DiffMerge. I installed DiffMerge, but I still didn’t get any diff window. My machine uses an Apple Silicon (M1/M2) chipset, so I’m not sure whether that’s related or if I’m missing an extra configuration step.

Based on this experience, I think the project would benefit from a short how-to guide explaining:

• how to install a diff tool, and
• how to configure ApprovalTests to correctly detect and launch it (especially on macOS / Apple Silicon).

I think this would make the onboarding experience much smoother for newcomers. Thanks!

[LarsEckart]

hey @ibanFR

we're having trouble reproducing this scenario. (works on my machine, it finds BeyondCompare and DiffMerge)
We could have a call together to see how we could improve the documentation for such a case.