Puppetarazzi NPM

Puppetarazzi

v0.2.24

Licensed under the MIT license

Introduction

Puppetarazzi uses puppeteer to load your site's pages in a headless Chrome browser in various simulated device resolutions, taking screenshots and capturing HAR files for each page/device combo.

While it's there, it'll do a check-up on your site's content and will annoy you by pointing out any flaws (mixed-content warnings, uncompressed content, 404s, etc).

Puppetarazzi contains a light-weight plugin infrastructure to easily add new checks, and each plugin can be enabled as needed.

Plugins

analytics: Verifies that analytics services send beacons for the page hit
asset-compression: Verifies that specific types of content are compressed with the required method
basic: Basic page validation (the response is 200 OK with content)
caching: Verifies that on a soft reload, all content is served from the disk cache, and that Cache-Control headers exist
har: Writes HAR files for each page load
hsts: Verifies HTTP Strict Transport Security is enabled
icons: Validates that rel='icon', rel='apple-touch-icon' and msapplication-TileImage icons exist
img-alt: Verifies all <img> have alt= attributes
meta: Verifies the specified <meta> tags exist
mixed-content: Verifies there are no Mixed-Content warnings
no-404s: Verifies there are no 404s
no-redirects: Verifies there weren't any redirects on the page
opengraph: Verifies pages have OpenGraph (and other) structured content
pwa: Verifies some of the Progressive Web App requirements
rel-canonical: Verifies <link rel='canonical'> tag exists
rel-search: Verifies <link rel='search'> tag exists
rss: Verifies RSS <link rel='alternate'> tags exist and the URL works
schema: Verifies schema.org types exist
screenshots: Takes screenshots for each page and device
tao: Verifies all assets have Timing-Allow-Origin set

Installation

Via npm:

npm install --global puppetarazzi

Usage

puppetarazzi [config.json]

Example configuration below:

{
    "name": "my-site",
    "root": "https://my-site.com",
    "verbose": true,
    "junit": "junit.xml",
    "postLoadSleep": 2000,
    "reloadAll": false,
    "plugins": {
        "basic": {},
        "analytics": {
            "require": [
                { "name": "google", "match": "google-analytics\\.com\\/.*\\/?collect.*" },
                { "name": "mPulse", "match": ".*akstat\\.io\\/*" }
            ]
        },
        "asset-compression": {
            "types": ["text/javascript", "text/css"],
            "encoding": ["gzip", "br"],
            "exclude": []
        },
        "caching": {
            // whether or not to exclude loading=lazy when ensuring on reload content is cached
            "excludeLazy": true,

            // exclude URLs
            "exclude": [
                "google-analytics\\.com\/collect",
                "c\\.go-mpulse\\.net\\/api\\/config\\.json",
                "\\.akstat\\.io\\/",
            ],
            "page": true
        },
        "har": {
            "output": "saved"
        },
        "hsts": {},
        "icons": {
            "required": [
                { "rel": "apple-touch-icon", "sizes": null },
                { "rel": "apple-touch-icon", "sizes": "72x72" },
                { "rel": "apple-touch-icon", "sizes": "114x114" },
                { "rel": "apple-touch-icon", "sizes": "144x144" },
                { "rel": "icon", "sizes": "16x16" },
                { "rel": "icon", "sizes": "32x32" },
                { "rel": "icon", "sizes": "48x48" },
                { "rel": "icon", "sizes": "64x64" },
                { "rel": "icon", "sizes": "96x96" }
            ],
            "tile": true
        },
        "img-alt": {
            "exclude": [
                "something\\.com",
            ],
        },
        "meta": {
            "required": [
                { "name": "msapplication-TileColor"},
                { "http-equiv": "Content-Type"},
                { "name": "robots", "content": "index,follow" },
                { "name": "description" },
                { "name": "viewport", "content": "width=device-width, initial-scale=1.0" }
            ]
        },
        "mixed-content": {
            "warnings": true
        },
        "no-404s": {},
        "no-redirects": {
            "exclude": [
                "something\\.com",
            ],
        },
        "opengraph": {
            "testImage": true,
            "twitter": true
        },
        "pwa": {
            "sw": true
        },
        "rel-canonical": {
            "https": true
        },
        "rel-search" : {},
        "rss": {
            "test": true
        },
        "schema": {
            "require": [
                "http://schema.org/WebPage",
                "http://schema.org/Organization",
                "http://schema.org/Article"
            ]
        },
        "screenshots": {
            "output": "saved",
            "atf": true,
            "full": true
        },
        "tao": {
            "exclude": []
        }
    },
    "pages": [
        { "name": "home", "path": "/", "reload": true },
        { "name": "blog", "path": "/blog/" }
    ],
    "devices": [
        { "name": "desktop-1920", "width": 1920, "height": 1080 },
        { "name": "desktop-1440", "width": 1440, "height": 900 },
        { "name": "desktop-1280", "width": 1280, "height": 800 },
        { "name": "desktop-1024", "width": 1024, "height": 768 },
        { "name": "ipad", "width": 768, "height": 1024 },
        { "name": "ipad-pro", "width": 1024, "height": 1366 },
        { "name": "iphone", "width": 375, "height": 667 },
        { "name": "iphone-plus", "width": 414, "height": 736 },
        { "name": "iphone-x", "width": 375, "height": 812 },
        { "name": "iphone-5", "width": 320, "height": 568 },
        { "name": "galaxy-s5", "width": 360, "height": 640 },
        { "name": "nexus-5x", "width": 412, "height": 732 },
        { "name": "galaxy-s8", "width": 360, "height": 740 },
        { "name": "galaxy-note-5", "width": 480, "height": 853 },
        { "name": "galaxy-tab-10", "width": 800, "height": 1280 },
        { "name": "kindle-fire-hdx", "width": 800, "height": 1280 }
    ],

    // if launching from a Docker container
    "puppeteerOptions": {
        "args": [
            "--no-sandbox",
            "--disable-setuid-sandbox"
        ]
    }
}

Each plugin (in plugins/*.js) has documentation on its options.

Global options:

name - Site name
root - Root URL
verbose - Whether or not to log verbose messages (default: false)
junit - jUnit XML file location (optional)
postLoadSleep - How many milliseconds to delay after load before running checks (optional)
reloadAll - Whether or not to trigger a reload of each page. Some plugins require this for their checks, e.g. asset-compression (default: false)
plugins - Each enabled plugin should be listed with its options
pages - A list of name, path and reload (optional) pairs
devices - A list of name, width and height pairs
puppeteerOptions - Options to pass to puppeteer.launch()
timeout - Timeout per page

Version History

v0.2.27 - 2024-08-28
- rss Does retries
v0.2.25 - 2024-08-01
- Add caching.excludeLazy option
v0.2.24 - 2020-05-15
- Use process.exit() after run is complete to force it to close
v0.2.23 - 2020-05-05
- Option waitUntil (puppet option) at global or page level
v0.2.22 - 2020-05-05
- har: Upgrade chrome-har dependency to avoid exception
v0.2.21 - 2020-05-03
- meta: Fix page-specific overrides when additional non-overwritten pages follow
v0.2.20 - 2020-05-03
- meta: Added page-specific overrides
v0.2.19 - 2018-11-24
- Added puppeteerOptions as a config JSON option for arguments to pass to puppeteer.launch()
v0.2.18 - 2018-07-10
- no-redirects, img-alt: Fixes for exclude if not specified
v0.2.17 - 2018-07-10
- no-redirects: Adds exclude option
v0.2.16 - 2018-07-10
- img-alt: Fixes exclude option
- asset-compression: Ignore data: URIs
v0.2.15 - 2018-07-05
- Fixes for several plugins that were finding elements on the page
v0.2.14 - 2018-07-05
- asset-compression: Allow exclude
v0.2.13 - 2018-07-05
- When Chrome crashes or throws an error, don't run plugins and just fail the page load
v0.2.12 - 2018-07-02
- img-alt, tao, icons, caching: Minor bug fixes
v0.2.11 - 2018-07-01
- If postLoadSleep is configured, sleep for the reload too
v0.2.10 - 2018-06-29
- har: Another fix for clearing old entries
v0.2.9 - 2018-06-29
- har: Was never clearing old entries
- har: Upgraded to latest chrome-har package to fix invalid har files
v0.2.8 - 2018-05-14
- img-alt: Has exclude option
v0.2.7 - 2018-04-20
- schema: Fix for page-specific overrides not updating the global config
- asset-compression: Fix for missing Content-Type
v0.2.6 - 2018-03-24
- basic: Allow for a 304 response
- caching: Allow for 304 on the page navigate
- no-redirects added
- opengraph: Log failure if found
- tao: Don't fail if no TAO on same domain as navigate
- puppetarazzi: Navigate to about:blank in between pages
v0.2.5 - 2018-03-23
- Catch exceptions around navigations and continue
v0.2.4 - 2018-03-22
- tao, caching: Skip data: URI
v0.2.3 - 2018-03-22
- asset-compression: Bug fixes
- img-alt: Share the missing URLs on failure
- rss: Share failure message
- schema: Allow per-page config
- tao: Skip destination page
- Show unhandled Promise rejections in console for debugging
v0.2.2 - 2018-03-08
- Launch a new browser for each device so repeated URL visits aren't cached from a previous device
v0.2.1 - 2018-03-08
- Fixed plugin load location when installed globally
v0.2.0 - 2018-03-08
- New plugins: basic, hsts, icons, img-alt, meta, rel-search, rss, tao
- asset-compression: Match Content-Types with ";' in them
- caching: Report separately on page vs asset compression (optional)
- caching: Report on Cache-Control headers
- opengraph: Only run testImage if the URL exists
- pwa: Option to disable ServiceWorker detection
v0.1.0 - 2018-03-04: Initial version