{"id":13552333,"url":"https://github.com/mmcc007/screenshots","last_synced_at":"2025-04-05T07:05:54.490Z","repository":{"id":48130814,"uuid":"166516417","full_name":"mmcc007/screenshots","owner":"mmcc007","description":"Screenshots: A command line utility and package for capturing screenshots for Flutter","archived":false,"fork":false,"pushed_at":"2022-01-11T20:56:34.000Z","size":10084,"stargazers_count":265,"open_issues_count":59,"forks_count":144,"subscribers_count":19,"default_branch":"master","last_synced_at":"2024-10-19T03:02:02.802Z","etag":null,"topics":["cicd","continuous-delivery","continuous-integration","dart","fastlane","flutter","flutter-package","screen-capture"],"latest_commit_sha":null,"homepage":"","language":"Dart","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mmcc007.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-01-19T06:55:05.000Z","updated_at":"2024-10-01T15:11:51.000Z","dependencies_parsed_at":"2022-08-12T19:20:30.242Z","dependency_job_id":null,"html_url":"https://github.com/mmcc007/screenshots","commit_stats":null,"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mmcc007%2Fscreenshots","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mmcc007%2Fscreenshots/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mmcc007%2Fscreenshots/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mmcc007%2Fscreenshots/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mmcc007","download_url":"https://codeload.github.com/mmcc007/screenshots/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247299832,"owners_count":20916190,"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":["cicd","continuous-delivery","continuous-integration","dart","fastlane","flutter","flutter-package","screen-capture"],"created_at":"2024-08-01T12:02:02.353Z","updated_at":"2025-04-05T07:05:54.471Z","avatar_url":"https://github.com/mmcc007.png","language":"Dart","funding_links":[],"categories":["Dart"],"sub_categories":[],"readme":"\n[![pub package](https://img.shields.io/pub/v/screenshots.svg)](https://pub.dartlang.org/packages/screenshots) \n[![Build Status](https://travis-ci.com/mmcc007/screenshots.svg?branch=master)](https://travis-ci.com/mmcc007/screenshots)\n[![Build status](https://ci.appveyor.com/api/projects/status/b6vlfyio9e21hxw8?svg=true)](https://ci.appveyor.com/project/mmcc007/screenshots)\n[![codecov](https://codecov.io/gh/mmcc007/screenshots/branch/master/graph/badge.svg)](https://codecov.io/gh/mmcc007/screenshots)\n\n![alt text][demo]\n\n[demo]: https://i.imgur.com/gkIEQ5y.gif \"Screenshot with overlaid \nstatus bar placed in frame\"  \nA screenshot image with overlaid status bar placed in a device frame.  \n\nFor an example of images generated with _Screenshots_ on a live app in both stores see:  \n[![GitErDone](https://play.google.com/intl/en_us/badges/images/badge_new.png)](https://play.google.com/store/apps/details?id=com.orbsoft.todo)\n[![GitErDone](https://linkmaker.itunes.apple.com/en-us/badge-lrg.svg?releaseDate=2019-02-15\u0026kind=iossoftware)](https://itunes.apple.com/us/app/giterdone/id1450240301)\n\n\nSee a demo of _Screenshots_ in action:\n[![Screenshots demo](https://i.imgur.com/V9VFSYb.png)](https://vimeo.com/317112577 \"Screenshots demo - Click to Watch!\")\n\nFor introduction to _Screenshots_ see https://medium.com/@nocnoc/automated-screenshots-for-flutter-f78be70cd5fd.\n\n# _Screenshots_\n\n_Screenshots_ is a standalone command line utility and package for capturing screenshot images for Flutter.   \n\n_Screenshots_ will start the required android emulators and iOS simulators (or find attached devices), run tests, process the captured screenshots, and drop them off to Fastlane for delivery to both stores.\n\n_Screenshots_ is inspired by three tools from Fastlane:  \n1. [Snapshots](https://docs.fastlane.tools/getting-started/ios/screenshots/)  \nThis is used to capture screenshots on iOS using iOS UI Tests.\n1. [Screengrab](https://docs.fastlane.tools/actions/screengrab/)  \nThis captures screenshots on android using Android Espresso tests.\n1. [FrameIt](https://docs.fastlane.tools/actions/frameit/)  \nThis is used to place captured iOS screenshots in a device frame.\n\nSince all three of these Fastlane tools do not work with Flutter, _Screenshots_ combines key features of these Fastlane tools into one tool. \n\n# Features\nSince Flutter integration testing is designed to work transparently across iOS and Android, capturing images using _Screenshots_ is easy.\n\nFeatures include: \n1. Works with existing tests  \nAdd a single line for each screenshot.\n1. Run tests on any device  \nSelect the devices to run on using a convenient config file. _Screenshots_ will find the devices (real or emulated) and run tests.\n1. One run for both platforms  \n_Screenshots_ runs tests on both iOS and Android in one run.  \n(as opposed to making separate Snapshots and Screengrab runs)\n1. One run for multiple locales  \nIf app supports multiple locales, _Screenshots_ will optionally set the locales listed in the config file before running each test.\n1. One run for frames  \nOptionally places images in device frames in same run.  \n(as opposed to making separate FrameIt runs... which supports iOS only)\n1. One run for clean status bars  \nEvery image that _Screenshots_ generates has a clean status bar.  \n(no need to run a separate stage to clean-up status bars)\n1. Works with Fastlane  \n_Screenshots_ drops-off images where Fastlane expects to find them. Fastlane's [deliver](https://docs.fastlane.tools/actions/deliver/) and [supply](https://docs.fastlane.tools/actions/supply/) can then be used to upload to respective stores.\n1. Works with FrameIt  \nWorks with Fastlane's FrameIt [text and background](https://docs.fastlane.tools/actions/frameit/#text-and-background) feature to add text, etc... to a framed screenshot generated by `screenshots`.  \n1. Works with any attached real devices  \nUse any number of real devices to capture screenshots.\n\nAdditional automation features:  \n1. _Screenshots_ runs in the cloud.  \nFor live demo of _Screenshots_ running with the internationalized [example](example) app on macOS, linux and windows in cloud, see [below](#sample-run-on-travis-and-appveyor)    \n1. _Screenshots_ works with any CI/CD tool.  \nFor live demo of uploading images, generated by _Screenshots_, to both store consoles, see demo of Fledge at https://github.com/mmcc007/fledge#demo\n\n# Installation\nOn macOS:\n````bash\nbrew update \u0026\u0026 brew install imagemagick\npub global activate screenshots\n````\n\nOn linux:\n````bash\n# Debian, Ubuntu or Linux Mint\nsudo apt-get install imagemagick\n# Fedora, CentOS or RHEL\nsudo yum install ImageMagick\n# OpenSUSE\nsudo zypper install imagemagick\n\npub global activate screenshots\n````\nNote: on linux ImageMagick is often already installed.\n\nOn windows:\n````bash\nchoco install imagemagick.app\npub global activate screenshots\n````\nNote: ImageMagick v7 or later is recommended on windows.\n\n\nIf `pub` is not found, add to PATH using:\n\nOn macOS/Linux:  \n```\nexport PATH=\"\u003cpath to flutter installation directory\u003e/bin/cache/dart-sdk/bin:$PATH\"\n```\nOn windows:\n```\nset PATH=\u003cpath to flutter installation directory\u003e\\flutter\\bin\\cache\\dart-sdk\\bin;%APPDATA%\\Pub\\Cache\\bin;%PATH%\n```\n\nNote: if running on Windows or Linux, can only run android devices/emulators. To also run on macOS use a CI that supports macOS.\n\n# Usage\n\n````\nscreenshots\n````\nOr, if using a config file other than the default 'screenshots.yaml':\n````\nscreenshots -c \u003cpath to config file\u003e\n````\nOther options:\n```\nusage: screenshots [-h] [-c \u003cconfig file\u003e] [-m \u003cnormal|recording|comparison|archive\u003e] [-f \u003cflavor\u003e] [-b \u003ctrue|false\u003e] [-v]\n\nsample usage: screenshots\n\n-c, --config=\u003cscreenshots.yaml\u003e                     Path to config file.\n                                                    (defaults to \"screenshots.yaml\")\n\n-m, --mode=\u003cnormal|recording|comparison|archive\u003e    If mode is recording, screenshots will be saved for later comparison.\n                                                    If mode is comparison, screenshots will be compared with recorded.\n                                                    If mode is archive, screenshots will be archived (and cannot be uploaded via fastlane).\n                                                    [normal (default), recording, comparison, archive]\n\n-f, --flavor=\u003cflavor name\u003e                          Flavor name.\n-b, --build=\u003ctrue|false\u003e                            Force build and install of app for all devices.\n                                                    Override settings in screenshots.yaml (if any).\n                                                    [true, false]\n\n-v, --verbose                                       Noisy logging, including all shell commands executed.\n-h, --help                                          Display this help information.\n```\n\n# Modifying tests for _Screenshots_\nA special function is provided in the _Screenshots_ package that is called by the test to capture a screenshot. \n_Screenshots_ will then process the images appropriately during a _Screenshots_ run.\n\nTo capture screenshots in tests:\n1. Add _Screenshots_ package in app's pubspec.yaml's dev_dependencies section  \n   ````yaml\n   dev_dependencies:\n     screenshots: ^\u003ccurrent version\u003e\n   ````\n2. In tests\n    1. Import the dependency  \n       ````dart\n       import 'package:screenshots/screenshots.dart';\n       ````\n    2. Create the config at start of test  \n       ````dart\n            final config = Config();\n       ````  \n    3. Throughout the test make calls to capture screenshots  \n       ````dart\n           await screenshot(driver, config, 'myscreenshot1');\n       ````\n       \nNote: make sure screenshot names are unique across all tests.\n\nNote: to turn off the debug banner, in the integration test's main(), call:\n````dart\n  WidgetsApp.debugAllowBannerOverride = false; // remove debug banner for screenshots\n````\n\n# Configuration\n_Screenshots_ uses a configuration file to configure a run.  \n The default config filename is `screenshots.yaml`:\n````yaml\n# A list of screen capture tests\ntests:\n# Note: flutter driver expects a pair of files eg, main1.dart and main1_test.dart\n  - test_driver/main1.dart \n  - test_driver/main2.dart \n\n# Interim location of screenshots from tests\nstaging: /tmp/screenshots\n\n# A list of locales supported by the app\nlocales:\n  - en-US\n  - de-DE\n\n# A map of devices to emulate\ndevices:\n  ios:\n    iPhone XS Max:\n    iPhone 11 Pro:\n      frame: false # no screen avail so frame must be false\n    iPad Pro (12.9-inch) (3rd generation):\n      orientation:\n        - Portrait # default \n        - LandscapeRight\n  android:\n    Nexus 6P:\n    SM G965F: # a real attached device (frame and orientation disabled)\n\n# Frame screenshots\nframe: true\n````\n\n## Device Parameters\nIndividual devices can be configured in `screenshots.yaml` by specifying per device parameters.\n\n| Parameter | Values | Required | Description |\n| --- | --- | --- | --- |\n|frame|true/false|optional|Controls whether screenshots generated on the device should be placed in a frame. Overrides the global frame setting (see example `screenshots.yaml` above).|\n|orientation|Portrait \\| LandscapeRight \\| PortraitUpsideDown \\| LandscapeLeft|optional|Controls orientation of device during test. Disables framing resulting in a raw screenshot. Ignored for real devices.|\n|build|true(default)/false|optional|Builds and installs app. When set to false, can be used for pre-installed apps that need to be configured before running tests.|\n\n_frame_ parameter notes:\n- images generated for devices where framing is disabled may not be suitable for upload.\n- set to false for devices unknown to _screenshots_.\n\n_orientation_ parameter notes:\n- multiple orientations can be specified. For example:\n    ```yaml\n        iPhone XS Max:\n          orientation:\n            - Portrait\n            - LandscapeRight\n    ```\n- landscape orientation disables framing  \n  This is because status/navigation bars in landscape mode are currently not implemented.\n- orientation on iOS simulators is implemented using an AppleScript script which requires granting permission on first use.\n\n## Test Options\nIn addition to using the default flutter driver mode, tests can also be specified using flutter driver parameters. For example:\n```\ntests:\n  - --target=test_driver/main1.dart --driver=test_driver/main1_test1.dart\n  - --target=test_driver/main2.dart --driver=test_driver/main2_test1.dart\n``` \n\n# Record/Compare Mode\n_Screenshots_ can be used to monitor any unexpected changes to the UI by comparing the new screenshots to previously recorded screenshots. Any differences will be highlighted in a 'diff' image for review.  \n\nTo use this feature:\n1. Add a recording directory to `screenshots.yaml`\n    ```yaml\n    recording: /tmp/screenshots_record\n    ```\n1. Run a recording to capture expected screenshots:\n    ```\n    screenshots -m recording\n    ```\n1. Run subsequent _Screenshots_ with:\n    ```\n    screenshots -m comparison\n    ```\n    _Screenshots_ will compare the new screenshots with the recorded screenshots and generate a 'diff' image for each screenshot that does not compare. The diff image highlights the differences in red.\n\n# Archive Mode\nTo generate screenshots for local use, such as generating reports of changes to UI over time, etc... use 'archive' mode. \n\nTo enable this mode:\n1. Add an archive directory to screenshots.yaml:\n    ```yaml\n    archive: /tmp/screenshots_archive\n    ```\n1. Run _Screenshots_ with:\n    ````\n    $ screenshots -m archive\n    ````\n\n# Integration with Fastlane\nSince _Screenshots_ is intended to be used with Fastlane, after _Screenshots_ completes, the images can be found in the project at:\n````\nandroid/fastlane/metadata/android\nios/fastlane/screenshots\n````\nImages are in a format suitable for upload via [deliver](https://docs.fastlane.tools/actions/deliver/) \nand [supply](https://docs.fastlane.tools/actions/supply/).\n\nTip: One way to use _Screenshots_ with Fastlane is to call _Screenshots_ before calling Fastlane (or optionally call from Fastlane). Fastlane (for either iOS or Android) will then find the images in the appropriate place.  \n\n(For a live demo of using Fastlane to upload screenshot images to both store consoles, see demo of Fledge at https://github.com/mmcc007/fledge#demo)\n\n## Fastlane FrameIt\niOS images generated by _Screenshots_ can also be further processed using FrameIt's [text and background](https://docs.fastlane.tools/actions/frameit/#text-and-background) feature.\n\n# Adding a device\n\n1. Confirm device is present in [screens.yaml](https://github.com/mmcc007/screenshots/blob/master/lib/resources/screens.yaml).  \n2. Add device to the list of devices in screenshots.yaml.  \n3. Confirm a real device is attached, or install an emulator/simulator for device.   \n\nIf screen is not available, disable framing by setting `frame: false` for the device.\n\n## Config validation\n_Screenshots_ will check configuration before running for errors and provide a guide on how to resolve.\n\n# Adding a screen\n\nIf device does not have a screen in screens.yaml please create an issue to request a new screen.\n\nTo submit a new screen please see related [README](https://github.com/mmcc007/screenshots/blob/master/test/resources/README.md).\n\n## Modifying tests based on screenshots environment\nIn some cases it is useful to know what device, device type, screen size, screen orientation and locale the test is currently running with. To obtain this information use:\n```\nfinal screenshotsEnv = config.screenshotsEnv;\n```\nSee https://github.com/flutter/flutter/issues/31609 for related `flutter driver` issue.\n\n# Upgrading\nTo upgrade, simply re-issue the install command\n````bash\n$ pub global activate screenshots\n````\nNote: the _Screenshots_ version should be the same for both the command line and in the `pubspec.yaml`.   \n1. If upgrading the command line version of _Screenshots_, also upgrade\n the version of _Screenshots_ in the pubspec.yaml.    \n2. If upgrading the version of _Screenshots_ in pubspec.yaml, also upgrade the command line version.\n\nTo check the version of _Screenshots_ currently installed:\n```\npub global list\n```\n\n# Sample run on Travis and Appveyor\nTo view _Screenshots_ running with the internationalized [example](example) app on macOS and linux in the cloud see:  \nhttps://travis-ci.com/mmcc007/screenshots\n\nTo view the images generated by _Screenshots_ during a run on travis see:  \nhttps://github.com/mmcc007/screenshots/releases/\n\nTo view a similar run on windows see:  \nhttps://ci.appveyor.com/project/mmcc007/screenshots\n\n* Running _Screenshots_ in the cloud is  useful for automating the generation of screenshots in a CI/CD environment.  \n* Running _Screenshots_ on macOS in the cloud can be used to generate screenshots when developing on Linux and/or Windows.\n\n# Related projects\nTo run integration tests on real devices in cloud:  \nhttps://github.com/mmcc007/sylph\n\nTo automate releases to both stores:  \nhttps://github.com/mmcc007/fledge\n\n# Issues and Pull Requests\n[Issues](https://github.com/mmcc007/screenshots/issues) and \n[pull requests](https://github.com/mmcc007/screenshots/pulls) are welcome.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmmcc007%2Fscreenshots","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmmcc007%2Fscreenshots","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmmcc007%2Fscreenshots/lists"}