{"id":15952626,"url":"https://github.com/skuzzle/snapshot-tests","last_synced_at":"2025-03-17T15:31:13.900Z","repository":{"id":37099964,"uuid":"404621654","full_name":"skuzzle/snapshot-tests","owner":"skuzzle","description":"Convenient snapshot testing for Java","archived":false,"fork":false,"pushed_at":"2025-02-12T15:28:42.000Z","size":1553,"stargazers_count":13,"open_issues_count":21,"forks_count":0,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-02-28T00:52:07.537Z","etag":null,"topics":["java","junit","junit5-extension","testing"],"latest_commit_sha":null,"homepage":"https://skuzzle.github.io/snapshot-tests/reference/latest/","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/skuzzle.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-09-09T07:08:32.000Z","updated_at":"2025-02-11T14:51:46.000Z","dependencies_parsed_at":"2024-01-16T13:23:56.515Z","dependency_job_id":"9f542f69-1739-4076-99a4-b9662a3683a9","html_url":"https://github.com/skuzzle/snapshot-tests","commit_stats":null,"previous_names":[],"tags_count":26,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skuzzle%2Fsnapshot-tests","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skuzzle%2Fsnapshot-tests/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skuzzle%2Fsnapshot-tests/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skuzzle%2Fsnapshot-tests/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/skuzzle","download_url":"https://codeload.github.com/skuzzle/snapshot-tests/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243865671,"owners_count":20360481,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["java","junit","junit5-extension","testing"],"created_at":"2024-10-07T13:09:19.634Z","updated_at":"2025-03-17T15:31:13.478Z","avatar_url":"https://github.com/skuzzle.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- This file is auto generated during release from readme/README.md --\u003e\n\n[![Maven Central](https://img.shields.io/static/v1?label=MavenCentral\u0026message=1.11.0\u0026color=blue)](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-bom/1.11.0/jar)\n[![JavaDoc](https://img.shields.io/static/v1?label=JavaDoc\u0026message=1.11.0\u0026color=orange)](http://www.javadoc.io/doc/de.skuzzle.test/snapshot-tests-core/1.11.0)\n[![Reference](https://img.shields.io/static/v1?label=Reference\u0026message=1.11.0\u0026color=orange)](https://skuzzle.github.io/snapshot-tests/reference/1.11.0)\n[![Coverage Status](https://coveralls.io/repos/github/skuzzle/snapshot-tests/badge.svg?branch=main)](https://coveralls.io/github/skuzzle/snapshot-tests?branch=main)\n[![Twitter Follow](https://img.shields.io/twitter/follow/ProjectPolly.svg?style=social)](https://twitter.com/ProjectPolly)\n\n# snapshot-tests\nConvenient snapshot testing for JUnit5 and JUnit4.\n\nThis library allows to conveniently assert on the structure and contents of complex objects. It does so by storing a\nserialized version of the object during the first test execution and during subsequent test executions, compare the\nactual object against the stored snapshot.\n\n- [x] Requires Java 11, supports Java 17\n\nSupported test frameworks:\n- [x] JUnit5  (tested against `5.10.1`) via [snapshot-tests-junit5](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-junit5/1.11.0/jar)\n- [x] JUnit4 (tested against `4.13.2`) via [snapshot-tests-junit4](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-junit4/1.11.0/jar)\n\nSupported snapshot formats:\n- [x] generic plain text (included by default via [snapshot-tests-core](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-core/1.11.0/jar))\n- [x] Json via [snapshot-tests-json](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-json/1.11.0/jar)\n- [x] XML via [snapshot-tests-xml](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-xml/1.11.0/jar) xor [snapshot-tests-xml-legacy](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-xml-legacy/1.11.0/jar)\n- [x] HTML via [snapshot-tests-html](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-html/1.11.0/jar)\n\nRead more about snapshot testing in this accompanying [blog post](https://simon.taddiken.net/the-case-for-snapshot-testing/).\n\n### Latest Maven Central coordinates\n\nPlease check out the GitHub release page to find Maven \u0026 Gradle coordinates for the latest\nrelease [1.11.0](https://github.com/skuzzle/snapshot-tests/releases/tag/v1.11.0)\n\n### Reference Documentation\nStarting with release `1.8.0` we provide a new external reference documentation:\n* [Latest](https://skuzzle.github.io/snapshot-tests/reference/latest): Always points to the latest version\n* [1.11.0](https://skuzzle.github.io/snapshot-tests/reference/1.11.0): Points to a specific version\n\nOver the course of the next releases most of the contents of this README will be transitioned into the new reference\ndocumentation.\n\n## Quick start\n_(assumes using `maven`, `JUnit5` and `snapshot-tests-json` artifact)_\n\nAdd the following dependencies to your build\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003ede.skuzzle.test\u003c/groupId\u003e\n    \u003cartifactId\u003esnapshot-tests-junit5\u003c/artifactId\u003e\n    \u003cversion\u003e1.11.0\u003c/version\u003e\n    \u003cscope\u003etest\u003c/scope\u003e\n\u003c/dependency\u003e\n\u003cdependency\u003e\n    \u003cgroupId\u003ede.skuzzle.test\u003c/groupId\u003e\n    \u003cartifactId\u003esnapshot-tests-json\u003c/artifactId\u003e\n    \u003cversion\u003e1.11.0\u003c/version\u003e\n    \u003cscope\u003etest\u003c/scope\u003e\n\u003c/dependency\u003e\n```\n\nAnnotate a test class with `@EnableSnapshotTests` and declare a `Snapshot` parameter in your test case:\n\n```java\n@EnableSnapshotTests\nclass ComplexTest {\n\n    private WhatEverService classUnderTest = ...;\n\n    @Test\n    void testCreateComplexObject(Snapshot snapshot) throws Exception {\n        ComplexObject actual = classUnderTest.createComplexObject();\n        snapshot.assertThat(actual).as(JsonSnapshot.json).matchesSnapshotStructure();\n    }\n}\n```\nSnapshot testing workflow:\n1. Implement your test cases and add one ore more snapshot assertions as shown above.\n2. When you now execute these tests the first time, serialized snapshots of your test results will be persisted\n**and the tests will fail**\n3. Execute the same tests again. Now, the framework will compare the test results against the persisted snapshots.\nIf your code under test produces deterministic results, tests should now be green\n4. Check in the persisted snapshots into your SCM\n\n\n## Notes on test framework support\n\n### JUnit5\nHistorically, JUnit5 is the preferred test framework and has always natively been supported. The preferred way of\nconfiguring the build is to add a dependency to `snapshot-tests-junit5` and optionally add a dependency for your\npreferred snapshot format (i.e. like `snapshot-tests-jackson`).\n\n### JUnit5 legacy\nThe `snapshot-tests-junit5` module has been introduced with version `1.8.0`. Prior to that, you would either add a\ndirect dependency to `snapshot-tests-core` or just use a single dependency to you preferred snapshot format which\nwould pull in the `-core` module transitively. This setup still works but is discouraged. You will see a warning being\nprinted to `System.err` stating the required migration steps.\n\n\u003e **Warning**\n\u003e Starting from version `2.0.0` this scenario will no longer be supported.\n\n### JUnit4\nJUnit4 support was introduced with version `1.8.0`. Add a dependency to  `snapshot-tests-junit4` and optionally\nadd a dependency for your preferred snapshot format like `snapshot-tests-jackson`.\n\n\u003e **Warning**\n\u003e In order to seamlessly support the JUnit5 legacy scenario described above, all snapshot format modules will still\n\u003e transitively pull in a JUnit5 dependency. Unfortunately this can only be fixed with the next major release. So long you\n\u003e might want to add a respective exclusion to your dependency:\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003ede.skuzzle.test\u003c/groupId\u003e\n    \u003cartifactId\u003esnapshot-tests-json\u003c/artifactId\u003e\n    \u003cversion\u003e1.11.0\u003c/version\u003e\n    \u003cscope\u003etest\u003c/scope\u003e\n    \u003cexclusions\u003e\n        \u003cexclusion\u003e\n            \u003cgroupId\u003eorg.junit.jupiter\u003c/groupId\u003e\n            \u003cartifactId\u003ejunit-jupiter-api\u003c/artifactId\u003e\n        \u003c/exclusion\u003e\n    \u003c/exclusions\u003e\n\u003c/dependency\u003e\n```\n\nor\n\n```\ntestImplementation('de.skuzzle.test:snapshot-tests-json:1.11.0') {\n    exclude group: 'org.junit.jupiter', module: 'junit-jupiter-api'\n}\n```\n\n## Usage\n\u003e NOTE: Most parts of this readme have been migrated to the new [reference documentation](#reference-documentation)\n\u003e and thus were already removed from the readme.\n\n### Configuring some more details\n**New**\nSince version `1.7.0` there is a new `@SnapshotTestOptions` annotation that can either be placed on a test method or\ntest class. It allows to configure some details of the snapshot testing engine.\n\n#### Showing more context in unified diffs\nUsing `@SnapshotTestOptions.textDiffContextLines()` you can advise the framework to print more lines surrounding a\ndetected change in the unified diffs. Per default, we will only print 5 lines around a change.\n\n\n#### Line number behavior in diffs\nBy default, line numbers in the diffs that are rendered in our assertion failure messages reflect the physical line\nnumber within the snapshot file. That number differs from the line number within the raw test result data because\nsnapshot files contain some header information at the beginning.\nIf you want line numbers in the diffs to reflect the number within the raw data, you can use\n\n```java\n@SnapshotTestOptions(renderLineNumbers = DiffLineNumbers.ACCORDING_TO_RAW_DATA)\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskuzzle%2Fsnapshot-tests","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fskuzzle%2Fsnapshot-tests","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskuzzle%2Fsnapshot-tests/lists"}