Package: approvaltests
ApprovalTests.PythonContentsWhat can I use ApprovalTests for?Getting StartedWhat Are ApprovalsNew ProjectsMinimal Example TutorialAdding to Existing ProjectsOverviewExample using pytestExample using unittestExample using CLIUsageArgument DefinitionsReportersSelecting a ReporterJSON file for collection of reportersSupport and DocumentationMissing Documentation?DependenciesRequired dependenciesExtra dependenciesFor developersWeekly EnsemblePull RequestsCapturing Human Intelligence - ApprovalTests is an open source assertion/verification library to aid testing.approvaltestsis the ApprovalTests port for Python.For more information see:www.approvaltests.com.What can I use ApprovalTests for?You can use ApprovalTests to verify objects that require more than a simple assert including long strings, large arrays,
and complex hash structures and objects. ApprovalTests really shines when you need a more granular look at the test
failure. Sometimes, trying to find a small difference in a long string printed to STDOUT is just too hard!ApprovalTests solves this problem by providing reporters which let you view the test results in one of many popular diff
utilities.Getting StartedWhat Are ApprovalsIf you need to gain a better understanding or are new to this concept, starthere.New ProjectsIf you are starting a new project, we suggest you use theStarter Project.
You can just clone this and go. It's great for exercises, katas, and green field projects.Minimal Example TutorialIf this is first time approvaltesting in python, consider starting here:Minimal Example TutorialAdding to Existing ProjectsFrompypi:pip install approvaltestsOverviewApprovals work by comparing the test results to a golden master. If no golden master exists you can create a snapshot
of the current test results and use that as the golden master. The reporter helps you manage the golden master.Whenever your current results differ from the golden master, Approvals will launch an external application for you to
examine the differences. Either you will update the master because you expected the changes and they are good,
or you will go back to your code and update or roll back your changes to get your results back in line with the
golden master.Example using pytestfromapprovaltests.approvalsimportverifydeftest_simple():result="Hello ApprovalTests"verify(result)snippet source|anchorInstall the plugin pytest-approvaltests and use it to select a reporter:pip install pytest-approvaltests
pytest --approvaltests-use-reporter='PythonNative'The reporter is used both to alert you to changes in your test output, and to provide a tool to update the golden
master. In this snippet, we chose the 'PythonNative' reporter when we ran the tests. For more information about selecting
reporters seethe documentationExample using unittestimportunittestfromapprovaltests.approvalsimportverifyclassGettingStartedTest(unittest.TestCase):deftest_simple(self):verify("Hello ApprovalTests")if__name__=="__main__":unittest.main()snippet source|anchorThis example has the same behaviour as the pytest version, but uses the built-in test frameworkunittestinstead.Example using CLIYou can invoke a verify() call from the command line. This allows invoking python approvals from any other stack via subprocesses.Usagepython -m approvaltests --test-id hello --received "hello world!"orpython -m approvaltests -t hello -r "hello world!"orecho "hello world!" | python -m approvaltests -t helloArgument Definitions--test-idor-t: Test identifier used to name theapproved.txtandreceived.txtfiles for the test.--receivedor-r: The output of the program under test (a string) that is passed to the verify method.stdin: Instead of providing areceivedargument, you may usestdin.ReportersSelecting a ReporterAll verify functions take an optionaloptionsparameter that can configure reporters (as well as many other aspects).ApprovalTests.Python comes with a few reporters configured, supporting Linux, Mac OSX, and Windows.In the example shown below, we pass in an options with a reporter we're selecting directly:classTestSelectReporterFromClass(unittest.TestCase):deftest_simple(self):verify("Hello",options=Options().with_reporter(report_with_beyond_compare()))snippet source|anchorYou can also use theGenericDiffReporterFactoryto find and select the first diff utility that exists on our system.An advantage of this method is you can modify the reporters.json file directly to handle your unique system.classTestSelectReporter(unittest.TestCase):defsetUp(self):self.factory=GenericDiffReporterFactory()deftest_simple(self):verify("Hello",options=Options().with_reporter(self.factory.get("BeyondCompare")))snippet source|anchorOr you can build your own GenericDiffReporter on the flyclassGettingStartedTest(unittest.TestCase):deftest_simple(self):verify("Hello",options=Options().with_reporter(GenericDiffReporter.create(r"C:\my\favorite\diff\utility.exe")),)snippet source|anchorAs long asC:/my/favorite/diff/utility.execan be invoked from the command line using the formatutility.exe file1 file2then it will be compatible with GenericDiffReporter. Otherwise you will have to derive your own reporter, which
we won't cover here.JSON file for collection of reportersTo wrap things up, I should note that you can completely replace the collection of reporters known to the reporter
factory by writing your own JSON file and loading it.For example if you hadC:/myreporters.json[["BeyondCompare4","C:/Program Files (x86)/Beyond Compare 4/BCompare.exe"],["WinMerge","C:/Program Files (x86)/WinMerge/WinMergeU.exe"],["Tortoise","C:/Program Files (x86)/TortoiseSVN/bin/tortoisemerge.exe"]]You could then use that file by loading it into the factory:importunittestfromapprovaltests.approvalsimportverifyfromapprovaltests.reporters.generic_diff_reporter_factoryimportGenericDiffReporterFactoryclassGettingStartedTest(unittest.TestCase):defsetUp(self):factory=GenericDiffReporterFactory()factory.load('C:/myreporters.json')self.reporter=factory.get_first_working()deftest_simple(self):verify('Hello',self.reporter)if__name__=="__main__":unittest.main()Of course, if you have some interesting new reporters inmyreporters.jsonthen please consider updating thereporters.jsonfile that ships with Approvals and submitting a pull request.Support and DocumentationDocumentationGitHub:https://github.com/approvals/ApprovalTests.PythonApprovalTests Homepage:http://www.approvaltests.comMissing Documentation?If there is documentation you wish existed, please add apage requesttothis issue.DependenciesApprovalTests require Python 3.8 or greater and the following dependencies:Required dependenciesThese dependencies are always required for approvaltestspytest>=4.0.0
empty-files>=0.0.3
typing_extensions>=3.6.2snippet source|anchorExtra dependenciesThese dependencies are required if you are going to use the related functionality
If you want the bare minimum you can use the pypi projectapprovaltests-minimalpyperclip>=1.5.29     # For Clipboard Reporter
beautifulsoup4>=4.4.0 # For verify_html
allpairspy>=2.1.0     # For PairwiseCombinations
mrjob>=0.7.4          # For MrJob
testfixtures >= 7.1.0 # For verify_logging
mock >= 5.1.0         # For verify_loggingsnippet source|anchorFor developersWeekly EnsembleThe best way to contribute is tojoin our weekly mob/ensemblePull RequestsPull requests are welcomed, particularly those accompanied by automated tests.To run the self-tests:./run_tests.shThis will run the self-tests on several python versions. We support python 3.8 and above.All pull requests will be pre-checked using GitHub actions to execute all these tests. You can see theresults of test
runs here.