feat(extractor): Add HTMLExtractor to PHP SDK for structured HTML data extraction

src/Extractors/HtmlExtractor.php

@@ -0,0 +1,55 @@
+<?php
+
+namespace VoltTest\Extractors;
+
+use VoltTest\Exceptions\VoltTestException;
+
+class HtmlExtractor implements Extractor
+{
+
+    private string $variableName;
+
+    private string $selector;
+
+    private ?string $attribute;
+
+    public function __construct(string $variableName, string $selector, ?string $attribute = null)
+    {
+        $this->variableName = $variableName;
+        $this->selector = $selector;
+        $this->attribute = $attribute;
+    }
+
+    public function toArray(): array
+    {
+        if (! $this->validate()) {
+            throw new VoltTestException('Invalid HTML Extractor');
+        }
+
+        return [
+            'variable_name' => $this->variableName,
+            'selector' => $this->selector,
+            'attribute' => $this->attribute,
+            'type' => 'html',
+        ];
+    }
+
+    public function validate(): bool
+    {
+        if (trim($this->variableName) === '') {
+            return false;
+        }
+
+        // Check for empty or whitespace-only selector
+        if (trim($this->selector) === '') {
+            return false;
+        }
+
+        // Check for empty or whitespace-only attribute
+        if ($this->attribute !== null && trim($this->attribute) === '') {
+            return false;
+        }
+
+        return true;
+    }
+}

src/Step.php

@@ -10,6 +10,7 @@
 use VoltTest\Extractors\CookieExtractor;
 use VoltTest\Extractors\Extractor;
 use VoltTest\Extractors\HeaderExtractor;
+use VoltTest\Extractors\HtmlExtractor;
 use VoltTest\Extractors\JsonExtractor;
 use VoltTest\Extractors\RegexExtractor;
 use VoltTest\Validators\StatusValidator;
@@ -191,6 +192,14 @@ public function extractFromRegex(string $variableName, string $selector): self
         return $this;
     }
 
+
+    public function extractFromHtml(string $variableName, string $selector, ?string $attribute = null): self
+    {
+        $htmlExtractor = new HtmlExtractor($variableName, $selector, $attribute);
+        $this->extracts[] = $htmlExtractor;
+        return $this;
+    }
+
     public function validateStatus(string $name, int $expected): self
     {
         $this->validations[] = new StatusValidator($name, $expected);

tests/Units/HtmlExtractorTest.php

@@ -0,0 +1,63 @@
+<?php
+
+namespace Tests\Units;
+
+use PHPUnit\Framework\TestCase;
+
+class HtmlExtractorTest extends TestCase
+{
+    private \VoltTest\Extractors\HtmlExtractor $htmlExtractor;
+
+    protected function setUp(): void
+    {
+        $this->htmlExtractor = new \VoltTest\Extractors\HtmlExtractor('testVar', 'div#test', 'data-id');
+    }
+
+    public function testToArray(): void
+    {
+        $expected = [
+            'variable_name' => 'testVar',
+            'selector' => 'div#test',
+            'attribute' => 'data-id',
+            'type' => 'html',
+        ];
+        $this->assertEquals($expected, $this->htmlExtractor->toArray());
+    }
+
+    public function testValidate(): void
+    {
+        $this->assertTrue($this->htmlExtractor->validate());
+    }
+
+    public function testEmptyVariableName(): void
+    {
+        $extractor = new \VoltTest\Extractors\HtmlExtractor('', 'div#test', 'data-id');
+        $this->assertFalse($extractor->validate());
+    }
+
+    public function testEmptySelector(): void
+    {
+        $extractor = new \VoltTest\Extractors\HtmlExtractor('testVar', '', 'data-id');
+        $this->assertFalse($extractor->validate());
+    }
+
+    public function testEmptyAttribute(): void
+    {
+        $extractor = new \VoltTest\Extractors\HtmlExtractor('testVar', 'div#test', '');
+        $this->assertFalse($extractor->validate());
+    }
+
+    public function testNullAttribute(): void
+    {
+        $extractor = new \VoltTest\Extractors\HtmlExtractor('testVar', 'div#test', null);
+        $this->assertTrue($extractor->validate());
+    }
+
+    public function testEmptyAttributeWithNullSelector(): void
+    {
+        $this->expectException(\VoltTest\Exceptions\VoltTestException::class);
+        $extractor = new \VoltTest\Extractors\HtmlExtractor('testVar', 'div#date', '');
+        $extractor->toArray();
+
+    }
+}

tests/Units/StepTest.php

@@ -117,6 +117,37 @@ public function testExtractFromJson(): void
         $this->assertEquals('json', $extract['type']);
     }
 
+    public function testExtractFromHtml(): void
+    {
+        $this->step->get(self::TEST_URL)
+            ->extractFromHtml('userId', 'div#user-id');
+        $stepArray = $this->step->toArray();
+        $extract = $stepArray['extract'][0];
+        $this->assertEquals('userId', $extract['variable_name']);
+        $this->assertEquals('div#user-id', $extract['selector']);
+        $this->assertEquals('html', $extract['type']);
+    }
+
+
+    public function testExtractFromHtmlWithAttribute(): void
+    {
+        $this->step->get(self::TEST_URL)
+            ->extractFromHtml('userId', 'div#user-id', 'data-id');
+        $stepArray = $this->step->toArray();
+        $extract = $stepArray['extract'][0];
+        $this->assertEquals('userId', $extract['variable_name']);
+        $this->assertEquals('div#user-id', $extract['selector']);
+        $this->assertEquals('html', $extract['type']);
+    }
+
+    public function testExtractFromHtmlThrowsException(): void
+    {
+        $this->expectException(VoltTestException::class);
+        $this->step->get(self::TEST_URL)
+            ->extractFromHtml('userId', '#div#user-id', '');
+        $this->step->toArray();
+    }
+
     public function testInvalidJsonPathThrowsException(): void
     {
         $this->expectException(InvalidJsonPathException::class);