[#165] Added on_every_step option and @screenshots tag support to capture screenshots on each step.

Author: AlexSkrypnyk

README.md

@@ -135,12 +135,41 @@ default:
       always_fullscreen: true
 ```
 
+### Capturing Screenshots After Every Step
+
+To automatically capture a screenshot after every step, you can either:
+
+1. **Enable globally** in configuration:
+
+```yaml
+default:
+  extensions:
+    DrevOps\BehatScreenshotExtension:
+      on_every_step: true
+```
+
+2. **Enable per-scenario** using the `@screenshots` tag:
+
+```gherkin
+@screenshots
+Scenario: My scenario with automatic screenshots
+  Given I am on "http://example.com"
+  When I click "Login"
+  Then I should see "Welcome"
+  # Screenshots will be captured after each of these steps
+```
+
+The `@screenshots` tag takes precedence over the global configuration, allowing you to enable this feature for specific scenarios even when it's disabled globally.
+
+**Note**: When both `on_every_step` and `on_failed` are enabled, only one screenshot is captured for failed steps (the failed screenshot) to avoid duplicates.
+
 ## Options
 
 | Name                      | Default value                                                          | Description                                                                                                                                                                                                                                                                                     |
 |---------------------------|------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | `dir`                     | `%paths.base%/screenshots`                                             | Path to directory to save screenshots. Directory structure will be created if the directory does not exist. Override with `BEHAT_SCREENSHOT_DIR` env var.                                                                                                                                       |
 | `on_failed`               | `true`                                                                 | Capture screenshot on failed test.                                                                                                                                                                                                                                                              |
+| `on_every_step`           | `false`                                                                | Automatically capture screenshots after every step. Can be enabled globally via config or per-scenario using the `@screenshots` tag. Only captures on passed steps to avoid duplicates with `on_failed`.                                                                                        |
 | `purge`                   | `false`                                                                | Remove all files from the screenshots directory on each test run. Useful during debugging of tests.                                                                                                                                                                                             |
 | `always_fullscreen`       | `false`                                                                | Always use fullscreen screenshot capture for all screenshot steps, including regular screenshot steps. When enabled, all `I save screenshot` steps will behave like `I save fullscreen screenshot`.                                                                                             |
 | `fullscreen_algorithm`    | `resize`                                                               | Algorithm to use for fullscreen screenshots. Options: `resize` (temporarily resizes browser window to full page height) or `stitch` (captures multiple screenshots while scrolling and stitches them together). The stitch algorithm requires GD extension but produces higher quality results. |

behat.yml.dist

@@ -8,6 +8,7 @@ default:
     DrevOps\BehatScreenshotExtension:
       dir: %paths.base%/screenshots
       on_failed: true
+      on_every_step: false # Capture screenshot after every step
       purge: false
       always_fullscreen: false
       fullscreen_algorithm: resize # 'stitch' (only if GD ext available) or 'resize'

src/DrevOps/BehatScreenshotExtension/Context/Initializer/ScreenshotContextInitializer.php

@@ -33,6 +33,8 @@ class ScreenshotContextInitializer implements ContextInitializer {
    *   Purge dir before start script.
    * @param bool $alwaysFullscreen
    *   Always take fullscreen screenshots.
+   * @param bool $onEveryStep
+   *   Capture screenshot after every step.
    * @param string $fullscreenAlgorithm
    *   Algorithm to use for fullscreen screenshots ('stitch' or 'resize').
    * @param string $filenamePattern
@@ -50,6 +52,7 @@ public function __construct(
     private readonly string $failedPrefix,
     protected bool $purge,
     protected bool $alwaysFullscreen,
+    protected bool $onEveryStep,
     protected string $fullscreenAlgorithm,
     protected string $filenamePattern,
     protected string $filenamePatternFailed,
@@ -77,6 +80,7 @@ public function initializeContext(Context $context): void {
         $this->onFailed,
         $this->failedPrefix,
         $this->alwaysFullscreen,
+        $this->onEveryStep,
         $this->fullscreenAlgorithm,
         $this->filenamePattern,
         $this->filenamePatternFailed,

src/DrevOps/BehatScreenshotExtension/Context/ScreenshotAwareContextInterface.php

@@ -22,6 +22,8 @@ interface ScreenshotAwareContextInterface extends Context {
    *   File name prefix for a failed test.
    * @param bool $always_fullscreen
    *   Always take fullscreen screenshots.
+   * @param bool $on_every_step
+   *   Capture screenshot after every step.
    * @param string $fullscreen_algorithm
    *   Algorithm to use for fullscreen screenshots ('stitch' or 'resize').
    * @param string $filename_pattern
@@ -33,7 +35,7 @@ interface ScreenshotAwareContextInterface extends Context {
    *
    * @return $this
    */
-  public function setScreenshotParameters(string $dir, bool $on_failed, string $failed_prefix, bool $always_fullscreen, string $fullscreen_algorithm, string $filename_pattern, string $filename_pattern_failed, array $info_types): static;
+  public function setScreenshotParameters(string $dir, bool $on_failed, string $failed_prefix, bool $always_fullscreen, bool $on_every_step, string $fullscreen_algorithm, string $filename_pattern, string $filename_pattern_failed, array $info_types): static;
 
   /**
    * Save screenshot content into a file.

src/DrevOps/BehatScreenshotExtension/Context/ScreenshotContext.php

@@ -33,6 +33,16 @@ class ScreenshotContext extends RawMinkContext implements ScreenshotAwareContext
    */
   protected bool $alwaysFullscreen = FALSE;
 
+  /**
+   * Capture screenshot after every step.
+   */
+  protected bool $onEveryStep = FALSE;
+
+  /**
+   * Whether the current scenario has the @screenshots tag.
+   */
+  protected bool $scenarioHasScreenshotsTag = FALSE;
+
   /**
    * Algorithm to use for fullscreen screenshots ('stitch' or 'resize').
    */
@@ -75,11 +85,12 @@ class ScreenshotContext extends RawMinkContext implements ScreenshotAwareContext
   /**
    * {@inheritdoc}
    */
-  public function setScreenshotParameters(string $dir, bool $on_failed, string $failed_prefix, bool $always_fullscreen, string $fullscreen_algorithm, string $filename_pattern, string $filename_pattern_failed, array $info_types): static {
+  public function setScreenshotParameters(string $dir, bool $on_failed, string $failed_prefix, bool $always_fullscreen, bool $on_every_step, string $fullscreen_algorithm, string $filename_pattern, string $filename_pattern_failed, array $info_types): static {
     $this->dir = $dir;
     $this->onFailed = $on_failed;
     $this->failedPrefix = $failed_prefix;
     $this->alwaysFullscreen = $always_fullscreen;
+    $this->onEveryStep = $on_every_step;
     $this->fullscreenAlgorithm = $fullscreen_algorithm;
     $this->filenamePattern = $filename_pattern;
     $this->filenamePatternFailed = $filename_pattern_failed;
@@ -98,6 +109,18 @@ public function getDir(): string {
     return $this->dir;
   }
 
+  /**
+   * Check if scenario has @screenshots tag.
+   *
+   * @param \Behat\Behat\Hook\Scope\BeforeScenarioScope $scope
+   *   Scenario scope.
+   *
+   * @BeforeScenario
+   */
+  public function beforeScenarioCheckScreenshotsTag(BeforeScenarioScope $scope): void {
+    $this->scenarioHasScreenshotsTag = $scope->getScenario()->hasTag('screenshots');
+  }
+
   /**
    * Init values required for screenshots.
    *
@@ -155,6 +178,28 @@ public function printLastResponseOnError(AfterStepScope $event): void {
     }
   }
 
+  /**
+   * Capture screenshot after every step when enabled.
+   *
+   * @param \Behat\Behat\Hook\Scope\AfterStepScope $event
+   *   After step scope event.
+   *
+   * @throws \Behat\Mink\Exception\DriverException
+   * @throws \Behat\Mink\Exception\UnsupportedDriverActionException
+   *
+   * @AfterStep
+   */
+  public function captureScreenshotAfterStep(AfterStepScope $event): void {
+    // Only capture if:
+    // 1. Global config is enabled OR scenario has the @screenshots tag
+    // 2. Step passed (we don't want duplicates with on_failed)
+    if (($this->onEveryStep || $this->scenarioHasScreenshotsTag) && $event->getTestResult()->isPassed()) {
+      $this->screenshot([
+        'fullscreen' => $this->alwaysFullscreen,
+      ]);
+    }
+  }
+
   /**
    * {@inheritdoc}
    *

src/DrevOps/BehatScreenshotExtension/ServiceContainer/BehatScreenshotExtension.php

@@ -73,6 +73,10 @@ public function configure(ArrayNodeDefinition $builder): void {
         ->cannotBeEmpty()
         ->defaultValue(FALSE)
       ->end()
+      ->scalarNode('on_every_step')
+        ->cannotBeEmpty()
+        ->defaultValue(FALSE)
+      ->end()
       ->enumNode('fullscreen_algorithm')
         ->values(['stitch', 'resize'])
         ->defaultValue('resize')
@@ -103,6 +107,7 @@ public function load(ContainerBuilder $container, array $config): void {
       $config['failed_prefix'],
       $config['purge'],
       $config['always_fullscreen'],
+      $config['on_every_step'],
       $config['fullscreen_algorithm'],
       $config['filename_pattern'],
       $config['filename_pattern_failed'],

tests/phpunit/Unit/BehatScreenshotExtensionTest.php

@@ -30,6 +30,7 @@ public function testLoad(): void {
       'failed_prefix' => 'failed_',
       'purge' => FALSE,
       'always_fullscreen' => FALSE,
+      'on_every_step' => FALSE,
       'fullscreen_algorithm' => 'resize',
       'filename_pattern' => '{datetime:U}.{feature_file}.feature_{step_line}.{ext}',
       'filename_pattern_failed' => '{datetime:U}.{failed_prefix}{feature_file}.feature_{step_line}.{ext}',
@@ -50,6 +51,7 @@ public function testLoad(): void {
         $config['failed_prefix'],
         $config['purge'],
         $config['always_fullscreen'],
+        $config['on_every_step'],
         $config['fullscreen_algorithm'],
         $config['filename_pattern'],
         $config['filename_pattern_failed'],
@@ -65,7 +67,7 @@ public function testConfigure(): void {
     $extension = new BehatScreenshotExtension();
     $extension->configure($builder);
 
-    $this->assertCount(9, $builder->getChildNodeDefinitions());
+    $this->assertCount(10, $builder->getChildNodeDefinitions());
   }
 
 }

tests/phpunit/Unit/Context/Initializer/ScreenshotContextInitializerTest.php

@@ -30,6 +30,7 @@ public function testInitializeContextNonScreenshotAware(): void {
       'failed_',
       TRUE,
       TRUE,
+      FALSE,
       'resize',
       '{datetime:U}.{ext}',
       '{datetime:U}.{failed_prefix}{ext}',
@@ -55,6 +56,7 @@ public function testInitializeContext(): void {
         TRUE,
         'failed_',
         TRUE,
+        FALSE,
         'resize',
         '{datetime:U}.{ext}',
         '{datetime:U}.{failed_prefix}{ext}',
@@ -68,6 +70,7 @@ public function testInitializeContext(): void {
       // don't purge.
       FALSE,
       TRUE,
+      FALSE,
       'resize',
       '{datetime:U}.{ext}',
       '{datetime:U}.{failed_prefix}{ext}',
@@ -97,6 +100,7 @@ public function testInitializeContextWithEnv(): void {
           TRUE,
           'failed_',
           TRUE,
+          FALSE,
           'resize',
           '{datetime:U}.{ext}',
           '{datetime:U}.{failed_prefix}{ext}',
@@ -133,6 +137,7 @@ public function testInitializeContextWithEnv(): void {
           // Not used due to ENV override.
           FALSE,
           TRUE,
+          FALSE,
           'resize',
           '{datetime:U}.{ext}',
           '{datetime:U}.{failed_prefix}{ext}',
@@ -155,6 +160,7 @@ public function testInitializeContextWithEnv(): void {
           TRUE,
           'failed_',
           TRUE,
+          FALSE,
           'resize',
           '{datetime:U}.{ext}',
           '{datetime:U}.{failed_prefix}{ext}',

tests/phpunit/Unit/ScreenshotContextInfoTest.php

@@ -67,6 +67,7 @@ public function testCompileInfo(array $info_types, array $expected_keys): void {
       TRUE,
       'failed_',
       FALSE,
+      FALSE,
       'stitch',
       '{datetime:U}.test.{ext}',
       '{datetime:U}.{failed_prefix}test.{ext}',
@@ -112,6 +113,7 @@ public function testCompileInfoUrlException(): void {
       TRUE,
       'failed_',
       FALSE,
+      FALSE,
       'stitch',
       '{datetime:U}.test.{ext}',
       '{datetime:U}.{failed_prefix}test.{ext}',
@@ -214,6 +216,7 @@ public function testMakeFileNameWithHostReplacement(): void {
         FALSE,
         'failed_',
         FALSE,
+        FALSE,
         'stitch',
         '{url}.{ext}',
         '{failed_prefix}{url}.{ext}',

tests/phpunit/Unit/ScreenshotContextResizeTest.php

@@ -145,6 +145,7 @@ public function testGetScreenshotFullscreenUsingResizeAlgorithm(): void {
       TRUE,
       'failed_',
       TRUE,
+      FALSE,
       'resize',
       '{datetime:U}.{feature_file}.feature_{step_line}.{ext}',
       '{datetime:U}.{failed_prefix}{feature_file}.feature_{step_line}.{ext}',
@@ -201,6 +202,7 @@ public function testScreenshotWithResizeAlgorithm(): void {
       'failed_',
     // always_fullscreen = TRUE.
       TRUE,
+      FALSE,
       'resize',
       '{datetime:U}.{feature_file}.feature_{step_line}.{ext}',
       '{datetime:U}.{failed_prefix}{feature_file}.feature_{step_line}.{ext}',