Missing Documentation Pages

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:

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

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";
}

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

@Kurru

@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?

@ScottBob

@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?

@Kurru

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

@Kurru

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

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

. D Remove broken links

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.

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!

@ibanFR

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.

Navigation Menu

Repository navigation

Missing Documentation Pages #342

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Missing Documentation Pages #342

Description

Activity

Kurru commented on Jan 24, 2023

Kurru commented on Jan 24, 2023

ScottBob commented on Feb 9, 2023

Kurru commented on Feb 10, 2023

ScottBob commented on Feb 16, 2023

ScottBob commented on Feb 16, 2023

patkujawa-wf commented on Sep 26, 2025

ScottBob commented on Dec 4, 2025

ibanFR commented on Jan 18, 2026

LarsEckart commented on Jan 19, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions