Configurable generation of screenshot filenames

[xurizaemon]

This introduces the ability to configure the filenames generated for screenshots more extensively, as proposed in https://github.com/drevops/behat-screenshot/issues/37.

There is a new configuration value filename_pattern which can be set in behat.yml or overridden with env var BEHAT_SCREENSHOT_FILENAME_PATTERN (as for BEHAT_SCREENSHOT_DIR).

This is a text string which permits use of the following tokens:

Token	Substituted with	Example value(s)
{datetime}	Current date in Ymd_His format	20231128_060912
{datetime:u}	Current date and time as microtime	1701105456.71
{ext}	Extension of the file captured	html or png
{fail_prefix}	Value of fail_prefix above	failed_, error
{feature_file}	Filename of the .feature file currently being executed	example.feature
{microtime}	Current microtime to two decimal places	1697358758.18
{step_line}	Line in the .feature file currently being executed	67
{step_text}	Text of the step currently being executed	I_am_on_the_test_page
{url}	URL of tested browser.	https_example_org_some_path
{url:host}, {url:path}, ...	URL components of tested browser (ref parse_url()).	some_path

If the new configuration values are not set, current filename behaviour will be preserved to avoid impact on any tooling which depends on BC here. Changed defaults could be introduced with an appropriate version increment (not proposed for this MR).

Test coverage and docs in PR hopefully clarify further.

Screenshots from early WIP:

Tasks

• [x] Docs
• [x] Test coverage
• [x] Implementation
• [x] Maintain existing behaviour by default for BC
• [x] Add {datetime} token
• [x] Add {path} token
• [x] Add {ext} and {fail_prefix} tokens
• [x] Add {feature_file}, {step_line} and {step_text} tokens
• [x] Add {url} and {url:*} (parse_url() components) tokens
• [x] Remove comparison with old implementation
• [x] rebase --autosquash
• [ ] Optional separate patterns for failed and successful screenshots
• [ ] {scenario_title}

Status

Feedback and input welcome, not ready for review yet - last commit is untested, currently moving tokens from variables on the context into an array to ensure safe values and avoid loading too many new variables onto the class.

Keeping test changes in a separate commit so I can patch the release with composer-patches.

[xurizaemon]

I feel like we should add @datetime with a format like 2022-07-15T173709.

Any requests?

[xurizaemon]

Ran into a couple of unrelated (?) issues getting tests to pass: #54, #56. Apologies 😀

[xurizaemon]

Separate patterns for fail & screenshot

Now that I see screenshots with more meaningful filenames, I realise that when I look at a fail screenshot I mostly want to see the failed step text @step_text, while on a standard screenshot something like @current_path is more likely to be useful information. I think having separate filename patterns for fail and success screenshots would be even better.

[AlexSkrypnyk]

@xurizaemon thank you so much for your contribution!

Could you please update the description with some examples of real-life file patterns that are different from what is available right now.

Also, could you please add examples of using some of the new tokens, like current page path or URL - if those will be used in the file names - I'd like to understand how they will be converted to path-friendly names.

Thank you

[xurizaemon]

Will do, rebased, current test failures are expected (related to prefix handling).

[AlexSkrypnyk]

@xurizaemon Can we please discuss this in an issue before implementation.

I've added my vision of the file naming spec https://github.com/drevops/behat-screenshot/issues/37#issuecomment-1765362632

Please note that an ability to specify different file names based on success/failure should be added in a separate issue. It would be great to progressively change things.

[AlexSkrypnyk]

@xurizaemon could you please pull from main - I have resolved some issues with abandoned Goutte driver.

[AlexSkrypnyk]

@xurizaemon I have some capa ity to pick this up in the next couple of weeks - can you please let me know if it is okay for me to do so or if you still want to finalise this yourself.

[xurizaemon]

Hey @AlexSkrypnyk - yeah totally happy for you to pick this up if that works 😄

WIP commits are a bit more I had locally, you can drop them (go back to 5fb570cc741631a0a174fcde9c77d74141e81dd7) or keep what makes sense, up to you.

[xurizaemon]

@tannguyen04 @AlexSkrypnyk I've added you as collaborators on this repo so you can continue this PR if that's suitable

[AlexSkrypnyk]

Implemented in https://github.com/drevops/behat-screenshot/pull/94