feat: Added a new CLI flag: --snapshot-patch-pycharm-diff

[UltimateLobster]

(Only relevant for Pycharm users) If the flag is passed, Syrupy will import and extend Pycharm's default diff script to provide more meaning full diffs when viewing snapshots mismatches in Pycharm's diff viewer

Description

When running snapshots tests in Pycharm (in fact, when running tests in general in Pycharm), it has this cool feature where you can see the difference between the expected and the actual objects in a diff viewer:

def test_example():
    expected = {
        "a": 1,
        "b": 2,
        "c": 3,
    }
    actual = {
        "a": 1,
        "b": 2,
        "c": 5,
    }
    assert actual== expected

After running test_example, and looking at Pycharm's console, we can see a link:

By clicking the <Click to see difference> link we can easily see the difference and know what the problem was:

However, lets run some snapshot tests this time:

@pytest.fixture
def json_snapshot(snapshot):
    return snapshot.with_defaults(extension_class=JSONSnapshotExtension)


def test_example(json_snapshot):
    actual = {
        "a": 1,
        "b": 2,
        "c": 5,
    }
    assert actual == json_snapshot

This time, Pycharm will show an incorrect difference that is hard to parse out:

This happens because Pycharm only sees an actual and an expected object, it doesn't have a way to know that the actual objects needs further parsing before the diff calculation.

This PR adds a new flag: --snapshot-patch-pycharm-diff. If the flag is active, Syrupy will attempt to import Pycharm's built-in teamcity-messages package (which Pycharm automatically adds to PYTHONPATH when running scripts in order to make it importable). If the import was successful, the teamcity.diff_tools.EqualsAssertionError object (which is responsible to calculating the string representation of the expected and actual objects in the diff view) will be patched.

The patched object will behave the same as before. However, if either the expected object or the actual objects are instances of syrupy.assertions.SnapshotAssertion, the expected and actual objects will be replaced by the snapshot's recalled data and asserted data respectively.

Now, if we activate the new flag, the diff will be meaningful again:

Related Issues

This PR should resolve #675 as well as the second part of #597

Checklist

• This PR has sufficient documentation.
• This PR has sufficient test coverage.
• [X ] This PR title satisfies semantic convention.

Additional Comments

As you might see in the checklist, there are a few missing parts in this PR. This is because I wasn't sure how to go about certain parts of the checklist.

1. At first I wanted to put the entire documentation in the README.md file (because that's where I saw the rest of the configuration going to. However, I wanted to put some images to have a more clear explanation and I wasn't sure where would be a good place to put them (if it is ok to put any at all).
2. I have no idea how should I go about testing this feature considering its results are accessible via Pycharm's UI.

[lindenwells]

Cool idea! You did what I wanted to but didn't have time to. You're right tho, it's kinda messy. Would this logic be better suited to living in PyCharm or does it absolutely need to be on the syrupy side?

[UltimateLobster]

Cool idea! You did what I wanted to but didn't have time to. You're right tho, it's kinda messy. Would this logic be better suited to living in PyCharm or does it absolutely need to be on the syrupy side?

I have no idea how Jetbrains manages their scripts, but the script in question is just a class that generically receives an "expected" and "actual" objects and formats them. It doubt Jetbrains would rush into adding extra code handling specifically for objects of a single library. Unless they offically add support for custom diff calculations (like a __calculate_diff__ or something to check on every object), I would assume the change would have to be strictly on Syrupy side.

Regardless, I guess it wouldn't hurt to ask around and check their stance on this issue.

[codecov]

Codecov Report

Attention: Patch coverage is 92.15686% with 4 lines in your changes missing coverage. Please review.

@@            Coverage Diff             @@
##             main     #864      +/-   ##
==========================================
- Coverage   98.31%   98.11%   -0.20%     
==========================================
  Files          20       21       +1     
  Lines        1545     1595      +50     
==========================================
+ Hits         1519     1565      +46     
- Misses         26       30       +4     

[noahnu]

I've added test coverage and will get this merged. Thank you for the contribution!

[noahnu]

🎉 This PR is included in version 4.7.0 🎉

The release is available on:

• v4.7.0
• GitHub release

Your semantic-release bot 📦🚀

[allcontributors]

@noahnu

I couldn't determine any contributions to add, did you specify any contributions?
Please make sure to use valid contribution names.

[noahnu]

@all-contributors add @UltimateLobster for code

[allcontributors]

@noahnu

I've put up a pull request to add @UltimateLobster! 🎉