{"id":20830408,"url":"https://github.com/javiertuya/visual-assert","last_synced_at":"2025-05-07T22:20:50.488Z","repository":{"id":39663741,"uuid":"437491282","full_name":"javiertuya/visual-assert","owner":"javiertuya","description":"Assertion methods that generate an html file with the differences highlighting the additions and deletions. Useful for comparing large strings or files. Available on Java and .NET.","archived":false,"fork":false,"pushed_at":"2025-05-03T05:31:32.000Z","size":268,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-03T06:25:11.002Z","etag":null,"topics":["assertions","differences","junit","mstest","reporting","testing"],"latest_commit_sha":null,"homepage":"","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/javiertuya.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,"zenodo":null}},"created_at":"2021-12-12T08:27:14.000Z","updated_at":"2025-05-03T05:31:35.000Z","dependencies_parsed_at":"2023-02-01T03:45:55.586Z","dependency_job_id":"367d52bf-4448-47c2-aff7-d80b4ab6925b","html_url":"https://github.com/javiertuya/visual-assert","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/javiertuya%2Fvisual-assert","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/javiertuya%2Fvisual-assert/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/javiertuya%2Fvisual-assert/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/javiertuya%2Fvisual-assert/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/javiertuya","download_url":"https://codeload.github.com/javiertuya/visual-assert/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252962673,"owners_count":21832371,"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":["assertions","differences","junit","mstest","reporting","testing"],"created_at":"2024-11-17T23:24:26.028Z","updated_at":"2025-05-07T22:20:50.476Z","avatar_url":"https://github.com/javiertuya.png","language":"Java","readme":"![Status](https://github.com/javiertuya/visual-assert/actions/workflows/test.yml/badge.svg)\n[![Maven Central](https://img.shields.io/maven-central/v/io.github.javiertuya/visual-assert)](https://central.sonatype.com/artifact/io.github.javiertuya/visual-assert)\n[![Nuget](https://img.shields.io/nuget/v/VisualAssert)](https://www.nuget.org/packages/VisualAssert/)\n\n# visual-assert\n\nAssertion methods that generate an html file with the differences highlighting the additions and deletions. \nUseful for comparing large strings or files.\nAvailable on Java and .NET platforms.\n\n- From Java include the `visual-assert` dependency as indicated in the \n  [Maven Central Repository](https://central.sonatype.com/artifact/io.github.javiertuya/visual-assert)\n- From .NET include the `VisualAssert` package in you project as indicated in \n  [NuGet](https://www.nuget.org/packages/VisualAssert/)\n\nMost of the .NET code and tests are converted from java using the [JavaToCsharp](https://github.com/paulirwin/JavaToCSharp) converter.\n\n## Usage\n\nFrom Java, instantiate the `VisualAssert` class and perform an assert:\n\n```java\nVisualAssert va = new VisualAssert();\nva.assertEquals(\"abc def ghi\\nmno pqr stu\", \"abc DEF ghi\\nother line\\nmno pqr stu\");\n```\n\nThis will produce an html file in the `target` directory that highlights the differences (additions in green, deletions in red):\n\n![diff-example](docs/diff-file-example.png \"Diff example\")\n\nThe assert statement is overloaded to specify an additional message and the name of the differences file \n(when the diff file name is not specified, a file `diff-n.html` is automatically generated, where `n` is an\nunique sequence number):\n\n```java\nva.assertEquals(String expected, String actual, String message)\nva.assertEquals(String expected, String actual, String message, String fileName)\n```\n\nFrom .NET, everything works like Java, only with these differences:\n\n- Method names are capitalized.\n- The destination folder is `reports`, located at the level of the project folder.\n\n## Specifying a test framework (java only)\n\nBy default, when the assertion fails, a java `AssertionError` is thrown,\nwhich does not require any particular test framework.\nIf you want also see the diffs from your developement environment, \nyou can specify a test framework that will raise the assertion failures:\n\n```java\nVisualAssert va = new VisualAssert().setFramework(Framework.JUNIT5);\n```\n\nJUnit 3, 4 and 5 are supported. Note that you will get a `NoClassDefFoundError` exception\nif the specified framework is not in the classpath.\n\n## Soft assertions\n\nSoft assertions do not throw an exception immediately when an assertion fails, \nbut record the assertion message and allow to continue the test and check other assertions.\n\n### Using soft assertions\n\nClass `SoftVisualAssert` implements this type of soft assertions:\n- After a number of calls to `assertEquals()`, calling `assertAll()` will throw the exception \n  if at least one previous assertion failed. The message aggregates the messages of all failed assertions.\n- If the soft assert instance is shared by more than one test, `assertClear()` must be called\n  before each sequence of assertions to reset the stored messages.\n- In addition to `assertEquals` a `fail` assertion is provided (the fail message is included\n  as the actual value compared with an empty expected value).\n\nExample:\n\n```java\nSoftVisualAssert va = new SoftVisualAssert();\nva.assertEquals(\"abc def ghi\\nmno pqr stu\", \"abc DEF ghi\\nother line\\nmno pqr stu\", \"this will fail\");\nva.assertEquals(\"abc def ghi\\nmno pqr stu\", \"abc def ghi\\nmno pqr stu\", \"this does not fail\")\nva.assertAll();\n```\n\n### Aggregate differencies\n\nBy default, each of the assertions that fail produces an html file with the differences.\nYou can obtain an aggregated view of all failed assertions by using one or both of the\nfollowing methods:\n\n- If a framework has been specified using `setFramework()` (java only) you can see the aggregated differences \n  from your development environment in the same way as with the native `assertEquals()`.\n- If you specify the name of an html file as argument to `assertAll(String htmlFile)`\n  the aggregated differences can be viewed by opening this file. \n\n## Customization\n\nThe behaviour of the `VisualAssert` and `SoftVisualAssert` instances can be customized by calling a number of setter methods. \nThese methods follow a fluent style, so as, they can be concatenated in a single statement.\n\n- `setReportSubdir(String reportSubdir)`: Sets the folder where generated files with the differences are stored (default is `target`).\n- `setNormalizeEol(boolean normalizeEol)`: If set to true, the compared strings are normalized to linux line-endings by removing all CR characters.\n- `setSoftDifferences(boolean useSoftDifferences)`: By default (hard), html differences are displayed inside a pre tag.\n  If set to true (soft), some whitespace differences and indentation may be hidden from the html output.\n- `setBrightColors(boolean useBrightColors)`: By default, differences are highlighted with pale red and green colors,\n  if set to true the colors are brighter to easily locate small differences.\n- `setDiffFileQualifier(String value)`: When assertions do not specify a diff file name, adds the indicated string to \n  the autogenerated diff file name.\n  Use this setting to get unique files when generating consolidated reports\n  from tests that run in different processes \n  (e.g. when run multiple modules, each in a different GitHub Actions job,\n  set a different qualifier in each module). \n- `setDiffFileEnvQualifier(String envVariable)`: When assertions do not specify a diff file name, adds the value of the\n  indicated environment variable to the autogenerated diff file name.\n  Use this setting to get unique files when generating consolidated reports\n  from tests that run in different processes and share the same codebase\n  (e.g. when run multiple modules, each in a different GitHub Actions job,\n  set the variable GITHUB_JOB in each module).\n  Note: Jobs that run in a matrix strategy share the same job name.\n  In this case the workflow should define an environment variable \n  to differentiate each matrix job. \n- `setUseLocalAbsolutePath(boolean useLocalAbsolutePath)`: If set to true, the link with the differences file will include a file url with the absolute path to the file,\n  useful when running tests from a development environment that allows links in the assertion messages (e.g. MS Visual Studio).\n- `setShowExpectedAndActual(boolean showExpectedAndActual)`: If set to true, the assert message will include the whole content of the exepcted and actual strings that are compared.\n\nThe `SoftVisualAssert` instances have an additional method to customize:\n- `setCallStackLength(int length)`: \n  Sets the number of call stack items that are shown for each failed assertion (default 1).\n  Use a value higher than 1 when the method that actually does the assert is not the test method\n  that should appear in the stack trace to locate the location of the failure.\n\n## Publish from a CI environment\n\nTo publish the files with differences to Jenkins you can include the following statement in some steop of the project Jenkinsfile:\n\n```yaml\narchiveArtifacts artifacts:'target/*.html', allowEmptyArchive:true\n```\n\nTo create an artifact including the files with differences using GitHub Actions, you can include the following step in your workflow:\n\n```yaml\n  - name: Publish test diff files\n    if: always()\n    uses: actions/upload-artifact@v2\n    with:\n      name: Diff files\n      path: target/*.html\n```\n\nWhen generating consolidated reports from multiple runs\n(e.g. JUnit html reports), the failed tests display the name of the diff files,\nbut the files must be browsed separately.\nTo link the diff files directly from the test report, the Github Action https://github.com/javiertuya/junit-report-action\nhas different options to both generate the reports and reprocess them to include the links to the diff files.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjaviertuya%2Fvisual-assert","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjaviertuya%2Fvisual-assert","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjaviertuya%2Fvisual-assert/lists"}