[Feature] Ability to customize the screenshot description on the image

[cenfun]

Context

Usually we need to share the screenshots with the team or someone. When opening the screenshot, it would be great if there is a related description on the screenshot, for example showing the test title and time.

What we tried

import { test } from '@playwright/test';

test('my test', async ({ page }, testInfo) => {

    await page.goto('https://playwright.dev/');

    const description = `Description for ${testInfo.title} (${new Date().toLocaleString()})`;

    // before screenshot, draw something in the page
    await page.evaluate(function(msg) {
        const elem = document.createElement('div');
        elem.className = 'screenshot-helper';
        elem.style.cssText = `pointer-events: none;
            position: absolute; z-index: 99999; 
            left: 20px; bottom: 20px; 
            font-size: 20px; font-weight: bold; padding: 5px 20px;
            opacity: 0.68; color: #ff0000; border: 1px solid red;`;
        elem.innerHTML = msg;
        document.body.appendChild(elem);
    }, description);

    // take screenshot
    await page.screenshot({
        path: testInfo.outputPath('my-screenshot.png')
    });

    // after screenshot, remove the helper message
    await page.evaluate(function(msg) {
        const elem = document.querySelector('.screenshot-helper');
        if (elem) {
            elem.remove();
        }
    });

});

Problem

We can only manually add the screenshot description, but not automatically add it when the test fails.

Suggested solution

Maybe we can consider adding an option to allow screenshot to support hooks, just like auto fixtures

// playwright.config.js
export default {

    use: {
        screenshot: 'only-on-failure'
    },
    screenshotFixture: async ({ page, testInfo }, use) => {
            // before screenshot
            await page.evaluate(...);

            // take screenshot
            await use();

            // after screenshot
            await page.evaluate(...);
    },
    reporter: [
        ['list']
    ]
};

or separate beforeScreenshot and afterScreenshot

// playwright.config.js
export default {

    use: {
        screenshot: 'only-on-failure'
    },
    beforeScreenshot: async ({ page, testInfo }) => {
            
    },
    afterScreenshot: async ({ page, testInfo }) => {
            
    },
    reporter: [
        ['list']
    ]
};

Thanks,

[mxschmitt]

Usually you use Trace Viewer to debug a failing test, there you see exactly how the website looked like for each step. (We don't recommend screenshots for debugging). If you use toHaveScreenshot inside your test for visual regression or any other expect matcher, you can add a message as a second parameter to the expect function.

Would that work for you?

[cenfun]

Thanks Max.
But the screenshots is not for debugging at the beginning, but for tracking the problem.
Usually QA engineer found the failed test first, then create a new jira tiket with the screenshots to the backlog, maybe in the next sprint it will be assigned to a developer to solve if the priority is not high. Therefore, if there is a description on the screenshot, it will be easy for developers to locate or reproduce the problem.
does that make sense?

[mxschmitt]

Sounds reasonable, I made a feature request out of it.

[pavelfeldman]

Why was this issue closed?

Thank you for your involvement. This issue was closed due to limited engagement (upvotes/activity), lack of recent activity, and insufficient actionability. To maintain a manageable database, we prioritize issues based on these factors.

If you have additional information not present in this issue that you think will help prioritizing it, please open a new issue and reference this one. More support or clarity on its necessity may prompt a review. Your understanding and cooperation are appreciated.