diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json new file mode 100644 index 0000000..b962ea7 --- /dev/null +++ b/.claude-plugin/marketplace.json @@ -0,0 +1,15 @@ +{ + "name": "sorge-it", + "description": "Skills for the PHP packages of Sorge IT.", + "owner": { + "name": "Stefan Sorge", + "url": "https://github.com/sorge-it" + }, + "plugins": [ + { + "name": "phpunit-pest-html-assertions", + "source": "./", + "description": "Check rendered HTML in PHPUnit and Pest tests with CSS selectors, never as a string." + } + ] +} diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..66bed93 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,13 @@ +{ + "name": "phpunit-pest-html-assertions", + "description": "Check rendered HTML in PHPUnit and Pest tests with CSS selectors, never as a string: the skill of sorge-it/phpunit-pest-html-assertions.", + "author": { + "name": "Stefan Sorge", + "url": "https://github.com/sorge-it" + }, + "homepage": "https://github.com/sorge-it/phpunit-pest-html-assertions", + "repository": "https://github.com/sorge-it/phpunit-pest-html-assertions", + "license": "MIT", + "keywords": ["php", "phpunit", "pest", "html", "testing", "css-selector"], + "skills": ["./resources/boost/skills/"] +} diff --git a/.gitattributes b/.gitattributes index 4149d48..8f6df29 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1,9 +1,15 @@ * text=auto eol=lf +/.claude-plugin export-ignore /.github export-ignore /.gitattributes export-ignore /.gitignore export-ignore +/CODE_OF_CONDUCT.md export-ignore +/CONTRIBUTING.md export-ignore +/SECURITY.md export-ignore /composer.lock export-ignore +/context7.json export-ignore +/demo export-ignore /fixtures export-ignore /phpstan.neon export-ignore /phpunit.xml export-ignore diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..77f733a --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,5 @@ + diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 1fa3fdd..973114a 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -56,3 +56,16 @@ jobs: - name: Test run: composer test + + # The demo app installs the package from this checkout, as a project does: PHPStan reports + # the string check, and Pest shows the line of the test, not a frame of the package. + # Both runs fail on purpose, so their output is read, not their exit code. + - name: Demo + working-directory: demo/app + run: | + composer install --no-interaction --no-progress + phpstan=$(vendor/bin/phpstan analyse --no-progress --error-format=json || true) + grep -q html.markupAsString <<< "$phpstan" + pest=$(vendor/bin/pest --colors=never tests/CartTest.php || true) + grep -q 'at tests/CartTest.php' <<< "$pest" + if grep -q 'src/PHPUnit/' <<< "$pest"; then echo 'A frame of the package is in the trace.'; exit 1; fi diff --git a/CHANGELOG.md b/CHANGELOG.md index 262545c..9d7bfcd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,41 @@ # Changelog +## 1.4.0 + +### Added + +- A guideline for Laravel Boost in `resources/boost/guidelines/core.blade.php`. Boost gives it to the + agent with every task, the skill only when a task needs it. Boost installs both once the package is + picked on `php artisan boost:install` or listed in `packages` of `boost.json`; the README said + before that Boost found the skill by itself. +- The skill installs in Claude Code as a plugin of this repository, and in other agents with + `npx skills add sorge-it/phpunit-pest-html-assertions`. See the README, section For coding agents. +- A demo in the README, recorded with VHS from the app in `demo/`. + +### Fixed + +- A failure points at the line of the test. Before, Pest showed the line in + `src/PHPUnit/Assertion.php` of this package, and the line of the test came only further down. The + package now adds its `src` directory to PHPUnit's `ExcludeList`, as PHPUnit does with its own + code. The printed trace of PHPUnit leaves out these frames too. `HTML_ASSERTIONS_SHOW_FRAMES=1`, + set in the shell, keeps them, for a bug report. The checkout of the package keeps them always. + +### Changed + +- The package requires Composer 2.1 (`composer-runtime-api: ^2.1`). +- Composer loads the new `src/PHPUnit/Autoload.php` in every process that loads `vendor/autoload.php`: + it adds the `src` directory to PHPUnit's `ExcludeList` and has no other effect. +- A deprecation triggered inside the package names PHPUnit as its source, not a third party. Its + category (self, direct, indirect) stays the same. +- A problem comes as a pull request, not as an issue: issues are closed. See CONTRIBUTING.md. +- A vulnerability is reported privately through GitHub, not by email. See SECURITY.md. + +### Upgrade + +- Composer 1 and Composer 2.0 stay on 1.3. Update Composer to 2.1 or later. +- A test that expects frames of this package in a trace runs with `HTML_ASSERTIONS_SHOW_FRAMES=1` + set in the shell. In `phpunit.xml` it comes too late: Composer loads the package first. + ## 1.3.0 ### Added diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..ccc2921 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,6 @@ +# Code of conduct + +This project follows the [Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/). + +Report unacceptable behavior to GitHub with "Report content" on the comment or pull request, or +through [GitHub's report form](https://github.com/contact/report-abuse). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..3d88bee --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,39 @@ +# Contributing + +Pull requests are welcome. Issues are closed: a problem comes as a pull request that fixes it. + +## A problem + +Open a pull request with: + +- a test that fails without the change; +- the change; +- a description of what went wrong and why the change fixes it. + +If you do not know how to fix it, describe the problem to a coding agent and let it draft the pull +request. Read the change and run the tests before you open it. + +In a project, a failure hides the frames of this package; the checkout of the package keeps them. To +see where a problem in your project comes from inside the package, run the test with +`HTML_ASSERTIONS_SHOW_FRAMES=1` set in the shell, for example +`HTML_ASSERTIONS_SHOW_FRAMES=1 vendor/bin/pest`. In `phpunit.xml` it comes too late. + +## A feature + +Open a pull request with tests and a section in the README. The package checks the HTML a server +renders; see "Not in scope" in the README. A feature outside of that is declined. + +## Before you open it + +```sh +composer test # Pint and Rector as a dry run, PHPStan at max, type coverage 100 %, the test suites +composer lint # Rector, then Pint +``` + +The code must run on PHP 8.3. When a message or the output of a check changes, record the demo again +with `make -C demo all` (needs Docker). + +## Review + +A pull request can be reviewed when it is ready for review and `composer test` passes in the CI. A +draft without activity can be closed. Pull requests opened in bulk are closed without review. diff --git a/README.md b/README.md index 2212407..1e09989 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,8 @@ [![Latest Version](https://img.shields.io/packagist/v/sorge-it/phpunit-pest-html-assertions)](https://packagist.org/packages/sorge-it/phpunit-pest-html-assertions) [![Total Downloads](https://img.shields.io/packagist/dt/sorge-it/phpunit-pest-html-assertions)](https://packagist.org/packages/sorge-it/phpunit-pest-html-assertions) [![License](https://img.shields.io/packagist/l/sorge-it/phpunit-pest-html-assertions)](LICENSE.md) +[![PHP Version](https://img.shields.io/packagist/php-v/sorge-it/phpunit-pest-html-assertions)](composer.json) +[![PHPStan](https://img.shields.io/badge/PHPStan-level%20max-brightgreen)](phpstan.neon) Check rendered HTML with CSS selectors, never as a string. Built for tests that AI coding agents write and run: in Laravel, Livewire, Symfony and TYPO3. @@ -15,50 +17,13 @@ expect($this->get('/cart')) ->not->toHaveSelector('[data-errors]'); ``` -**Works with:** PHPUnit · Pest · Laravel · Livewire · Symfony · TYPO3 · PSR-7 · Laravel Boost · PHPStan · Rector +**Works with:** PHPUnit · Pest · Laravel · Livewire · Symfony · TYPO3 · PSR-7 · Laravel Boost · Claude Code · PHPStan · Rector -## Why - -Coding agents write a large share of our tests. Left alone, they check HTML the way it is easiest to -type: `assertSee('')`, a regular expression over the markup. Those tests fail when -one more `` wraps a dot, though the page looks the same. And they pass when the text they look -for sits only in an attribute or a script. - -This package asks the DOM instead. `symfony/dom-crawler` parses the page with `Dom\HTMLDocument`, as -a browser does, and every check selects with CSS. - -## Built for coding agents - -Each part of the package acts at one step of the loop in which an agent writes a test: - -| Step | Part | -|---|---| -| Before the agent writes | A [Laravel Boost](#laravel-boost) skill gives the agent the checks and the rules for selectors. | -| When the agent checks its work | The [PHPStan rules](#phpstan) `html.markupAsString` and `html.classAsString` report a check of markup or of a class as a string and say what to use instead. | -| When a test fails | The [message](#when-a-check-fails) names the region, what was asked, what was found, and shows the HTML of the region. The agent can fix the test without a browser. | -| In an existing suite | A [Rector rule](#rector) rewrites the mechanical forms of crawler code. | - -## Parts - -The package has four parts: - -| Part | Namespace | What it holds | -|---|---|---| -| PHPUnit | `SorgeIt\PhpunitPestHtmlAssertions\PHPUnit` | the constraints, `Html` (a page or a region of it) and the `AssertsHtml` trait | -| Pest | `SorgeIt\PhpunitPestHtmlAssertions\Pest` | the expectations and the function `html()` | -| PHPStan | `SorgeIt\PhpunitPestHtmlAssertions\PHPStan` | the rules `html.markupAsString` and `html.classAsString`, which report a check of markup or of a class as a string | -| Rector | `SorgeIt\PhpunitPestHtmlAssertions\Rector` | a rule that rewrites the mechanical forms of crawler code | - -## Requirements - -- PHP 8.3, 8.4 or 8.5 -- PHPUnit 12.5 or 13 -- Pest 4 or 5, optional, for the expectations -- the PHP extensions `dom` and `mbstring` -- Symfony DomCrawler and CssSelector 7.4 or 8.1 +![PHPStan reports a check of markup as a string; the check by selector fails and shows the region](https://raw.githubusercontent.com/sorge-it/phpunit-pest-html-assertions/main/demo/output/demo.gif) -The CI tests three stacks: PHP 8.3 with PHPUnit 12, Pest 4, Laravel 12 and Symfony 7.4; PHP 8.4 with -the newest versions; PHP 8.5 with the versions of `composer.lock`. +PHPStan reports a check of markup as a string. The check by selector fails, names the region, +gives the reason and shows the HTML of the region, at the line of the test. The demo is recorded +from the app in [`demo/`](demo). ## Installation @@ -102,6 +67,60 @@ final class CartTest extends TestCase Every method of the trait starts with `assertHtml`. So the trait also works in a Symfony `WebTestCase`, which has its own `assertSelectorExists()` and similar methods. +## Why + +Coding agents write many tests. Without help, they check HTML the way it is easiest to type: +`assertSee('')`, a regular expression over the markup. Those tests fail when one +more `` wraps a dot, though the page looks the same. And they pass when the text they look for +sits only in an attribute or a script. + +This package reads the DOM instead. `symfony/dom-crawler` parses the page with `Dom\HTMLDocument`, as +a browser does, and every check selects with CSS. + +## Compared with + +| Tool | What it checks | The difference | +|---|---|---| +| `assertSee()`, `assertSeeHtml()`, `toContain()` | a string | passes on text in an attribute or a script, fails when the markup around the text changes | +| Symfony's `assertSelectorTextContains()` and the other `assertSelector…()` methods | CSS selectors | only in a `WebTestCase`, on the client's last response; no regions; the message shows no HTML | +| `sinnbeck/laravel-dom-assertions` | CSS selectors | Laravel's test responses, views and Livewire components; this package also reads Symfony, TYPO3 and PSR-7 responses and adds PHPStan rules | +| Laravel Dusk, Pest's browser tests | a real browser | for JavaScript, CSS and clicks; slower. This package checks the HTML the server renders, in a unit or feature test | +| HTML snapshots | the whole page | fail on every change; an update accepts the whole new page | + +## Built for coding agents + +The package acts at each step of the loop in which an agent writes a test: + +| Step | What acts | +|---|---| +| Before the agent writes | A [skill](#for-coding-agents) gives the agent the checks and the rules for selectors: through Laravel Boost, Claude Code or the `skills` CLI. Boost also adds a short guideline to every task. | +| When the agent checks its work | The [PHPStan rules](#phpstan) `html.markupAsString` and `html.classAsString` report a check of markup or of a class as a string and say what to use instead. | +| When a test fails | The [message](#when-a-check-fails) names the region, what was asked, what was found, and shows the HTML of the region. It points at the line of the test, not into this package. The agent can fix the test without a browser. | +| In an existing suite | A [Rector rule](#rector) rewrites the mechanical forms of crawler code. | + +## Requirements + +- PHP 8.3, 8.4 or 8.5 +- PHPUnit 12.5 or 13 +- Pest 4 or 5, optional, for the expectations +- the PHP extensions `dom` and `mbstring` +- Symfony DomCrawler and CssSelector 7.4 or 8.1 +- Composer 2.1 or later + +The CI tests three stacks: PHP 8.3 with PHPUnit 12, Pest 4, Laravel 12 and Symfony 7.4; PHP 8.4 with +the newest versions; PHP 8.5 with the versions of `composer.lock`. + +## Namespaces + +| Namespace | What it holds | +|---|---| +| `SorgeIt\PhpunitPestHtmlAssertions\PHPUnit` | the constraints, `Html` (a page or a region of it) and the `AssertsHtml` trait | +| `SorgeIt\PhpunitPestHtmlAssertions\Pest` | the expectations and the function `html()` | +| `SorgeIt\PhpunitPestHtmlAssertions\PHPStan` | the rules `html.markupAsString` and `html.classAsString`, which report a check of markup or of a class as a string | +| `SorgeIt\PhpunitPestHtmlAssertions\Rector` | a rule that rewrites the mechanical forms of crawler code | + +The guideline and the skill for coding agents lie in `resources/boost/`. + ## What a check reads Each check takes one of these: @@ -133,7 +152,7 @@ Each row gives the call and the sentence of its message when it fails, after the | `toHaveSelector('[data-cart]')` | `assertHtmlSelectorExists` | has a node matching "[data-cart]" | | — | `assertHtmlSelectorNotExists` | does not have a node matching "[data-cart]" | | `toHaveSelectorCount('li', 3)` | `assertHtmlSelectorCount` | has 3 nodes matching "li" | -| `toHaveSelectorCountAtLeast('li', 1)` | `assertHtmlSelectorCountAtLeast` | has at least 1 nodes matching "li" | +| `toHaveSelectorCountAtLeast('li', 2)` | `assertHtmlSelectorCountAtLeast` | has at least 2 nodes matching "li" | | `toHaveSelectorText('h1', 'Orders')` | `assertHtmlSelectorTextSame` | has one node matching "h1" with the text "Orders" | | `toHaveSelectorTextContaining('h1', 'Ord')` | `assertHtmlSelectorTextContains` | has one node matching "h1" whose text contains "Ord" | | `toHaveAnySelectorText('li', 'Apple')` | `assertHtmlAnySelectorTextSame` | has a node matching "li" with the text "Apple" | @@ -145,7 +164,7 @@ Each row gives the call and the sentence of its message when it fails, after the | `toHaveSelectorClass('[data-status]', 'bg-red-500')` | `assertHtmlSelectorClass` | has one node matching "[data-status]" with the class "bg-red-500" | | `toHaveText('Apple Pear')` | `assertHtmlTextSame` | has the text "Apple Pear" | | `toHaveTextContaining('Apple')` | `assertHtmlTextContains` | has a text that contains "Apple" | -| `toHaveTextCount('Apple', 1)` | `assertHtmlTextCount` | has the text "Apple" 1 times | +| `toHaveTextCount('Apple', 2)` | `assertHtmlTextCount` | has the text "Apple" 2 times | | `toAppearBefore('[data-head]', '[data-body]')` | `assertHtmlSelectorBefore` | has the node matching "[data-head]" before the node matching "[data-body]" | | `toHaveTitle('Orders')` | `assertHtmlPageTitleSame` | has the title "Orders" | | `toHaveInputValue('email', 'anna@example.com')` | `assertHtmlInputValueSame` | has one field named "email" with the value "anna@example.com" | @@ -278,9 +297,13 @@ NotOneNode: (page) > [data-cart]: a check of one node needs exactly one match. T `dump()` and `dd()` of Pest show the same path and region. +A failure points at the line of the test. The trace leaves out the frames of this package, as it +leaves out those of PHPUnit. For a bug report, run the test with `HTML_ASSERTIONS_SHOW_FRAMES=1` +set in the shell, not in `phpunit.xml`: the trace then keeps them. + ## Which selector -1. The element, its role, `aria-*`, its label or its visible text. +1. The tag, its role, `aria-*`, its label or its visible text. 2. A `data-*` marker: the functional marker that the app (Alpine, scripts) and the tests share. A CSS class is for the look, not for a selector. 3. A class is a value to check (`toHaveSelectorClass('[data-status]', 'bg-red-500')`), not the @@ -416,31 +439,50 @@ change slightly: `texts()` leaves out a script, a style or a `template` inside a Add it to the `rector.php` of a project for a migration: `->withRules([CrawlerToHtmlRector::class])`. -## Laravel Boost +## For coding agents + +The package ships a skill in the [Agent Skills](https://agentskills.io) format and a short guideline +for Laravel Boost. With them, an agent writes these checks instead of string checks. + +**Laravel Boost** lists the package on `php artisan boost:install`, also as a `require-dev` +dependency. Pick it in the list of third-party guidelines and skills, or add it to `packages` in +`boost.json`. Boost then writes the guideline into the guideline file of the agent, for example +`CLAUDE.md`, and installs the skill: + +```json +{ + "packages": ["sorge-it/phpunit-pest-html-assertions"] +} +``` + +**Claude Code** installs the skill as a plugin of this repository: -The package ships a skill for [Laravel Boost](https://github.com/laravel/boost) in -`resources/boost/skills/`. Boost finds it in every direct dependency and gives it to your coding -agent, so the agent writes these checks instead of string checks. +``` +/plugin marketplace add sorge-it/phpunit-pest-html-assertions +/plugin install phpunit-pest-html-assertions@sorge-it +``` + +**Other agents** (Cursor, Codex, GitHub Copilot and more) install it with the +[`skills` CLI](https://github.com/vercel-labs/skills): + +```sh +npx skills add sorge-it/phpunit-pest-html-assertions +``` ## Not in scope - CSS: whether a rule takes effect is a question for a browser test (`getComputedStyle`). - Accessibility: `axe-core` in a browser test. -- HTML snapshots: a snapshot takes every change as the new truth. +- HTML snapshots: see [Compared with](#compared-with). ## Development -```sh -composer test # Pint and Rector as a dry run, PHPStan at max, type coverage 100 %, the test suites -composer lint # Rector, then Pint -``` - -Bug reports and pull requests are welcome on -[GitHub](https://github.com/sorge-it/phpunit-pest-html-assertions/issues). +A problem comes as a pull request that fixes it, not as an issue. How to run the checks of the +package: [CONTRIBUTING.md](CONTRIBUTING.md). ## Security -Please report a security problem by email to github@sorge-it.de, not in a public issue. +Report a vulnerability privately through GitHub. See [SECURITY.md](SECURITY.md). ## License diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..11b6529 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,14 @@ +# Security policy + +## Supported versions + +The latest minor release of 1.x. A fix is released there only. + +## Reporting a vulnerability + +Do not report a vulnerability in a public pull request. Report it privately through GitHub: +[Report a vulnerability](https://github.com/sorge-it/phpunit-pest-html-assertions/security/advisories/new). + +If you have a fix, add it in the private fork of the advisory. There is no fixed response time. + +The package runs in test suites (`require-dev`), not in production code. diff --git a/composer.json b/composer.json index 12a2066..226f48b 100644 --- a/composer.json +++ b/composer.json @@ -1,9 +1,9 @@ { "name": "sorge-it/phpunit-pest-html-assertions", - "description": "HTML assertions for PHPUnit and Pest: check rendered HTML with CSS selectors, never as a string. With two PHPStan rules and a Rector rule.", + "description": "HTML assertions for PHPUnit and Pest: check rendered HTML with CSS selectors, never as a string. With PHPStan rules, a Rector rule and a skill for AI coding agents.", "type": "library", "license": "MIT", - "keywords": ["phpunit", "pest", "html", "dom", "css-selector", "assertions", "laravel", "livewire", "symfony", "typo3", "laravel-boost", "ai-agents"], + "keywords": ["phpunit", "pest", "html", "dom", "css-selector", "assertions", "testing", "laravel", "livewire", "blade", "symfony", "typo3", "dom-crawler", "phpstan", "phpstan-extension", "rector", "tailwind", "laravel-boost", "ai-agents", "agent-skills", "claude-code"], "homepage": "https://github.com/sorge-it/phpunit-pest-html-assertions", "authors": [ { @@ -12,13 +12,15 @@ } ], "support": { - "issues": "https://github.com/sorge-it/phpunit-pest-html-assertions/issues", - "source": "https://github.com/sorge-it/phpunit-pest-html-assertions" + "source": "https://github.com/sorge-it/phpunit-pest-html-assertions", + "docs": "https://github.com/sorge-it/phpunit-pest-html-assertions#readme", + "security": "https://github.com/sorge-it/phpunit-pest-html-assertions/security/policy" }, "require": { "php": "^8.3", "ext-dom": "*", "ext-mbstring": "*", + "composer-runtime-api": "^2.1", "phpunit/phpunit": "^12.5|^13.2", "symfony/css-selector": "^7.4|^8.1", "symfony/dom-crawler": "^7.4|^8.1", @@ -47,6 +49,7 @@ "SorgeIt\\PhpunitPestHtmlAssertions\\": "src/" }, "files": [ + "src/PHPUnit/Autoload.php", "src/Pest/Autoload.php" ] }, diff --git a/composer.lock b/composer.lock index 546b81c..0193a39 100644 --- a/composer.lock +++ b/composer.lock @@ -4,7 +4,7 @@ "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies", "This file is @generated automatically" ], - "content-hash": "1caa03f3bbc90f8832eba1dc76e43cfd", + "content-hash": "149072daa33c3ff7a6e66934c19842d6", "packages": [ { "name": "myclabs/deep-copy", @@ -7615,7 +7615,8 @@ "platform": { "php": "^8.3", "ext-dom": "*", - "ext-mbstring": "*" + "ext-mbstring": "*", + "composer-runtime-api": "^2.1" }, "platform-dev": {}, "plugin-api-version": "2.9.0" diff --git a/context7.json b/context7.json new file mode 100644 index 0000000..e51f24c --- /dev/null +++ b/context7.json @@ -0,0 +1,14 @@ +{ + "$schema": "https://context7.com/schema/context7.json", + "projectTitle": "phpunit-pest-html-assertions", + "description": "HTML assertions for PHPUnit and Pest: check rendered HTML with CSS selectors, never as a string.", + "folders": [], + "excludeFolders": ["demo", "fixtures", "stubs", "tests", "vendor"], + "excludeFiles": ["CHANGELOG.md", "CODE_OF_CONDUCT.md", "SECURITY.md"], + "rules": [ + "Check rendered HTML with a CSS selector, never as a string or a regular expression.", + "Select by tag, role, aria-*, label or text, then by a data-* marker; a class is a value to check with toHaveSelectorClass().", + "A check of one node needs exactly one match; narrow to a region with within().", + "Give a check its reason as the last argument; after the optional value of toHaveSelectorAttribute(), pass it by name: message: '…'." + ] +} diff --git a/demo/.gitignore b/demo/.gitignore new file mode 100644 index 0000000..f2dc7fc --- /dev/null +++ b/demo/.gitignore @@ -0,0 +1,3 @@ +/app/vendor/ +/app/composer.lock +/app/.phpstan/ diff --git a/demo/Dockerfile b/demo/Dockerfile new file mode 100644 index 0000000..e6919f2 --- /dev/null +++ b/demo/Dockerfile @@ -0,0 +1,10 @@ +# VHS records the terminal; PHP and Composer run the demo app inside it. +FROM ghcr.io/charmbracelet/vhs:v0.12.1 + +RUN apt-get update \ + && apt-get install -y --no-install-recommends php-cli php-xml php-mbstring unzip git \ + && rm -rf /var/lib/apt/lists/* + +COPY --from=composer:2 /usr/bin/composer /usr/local/bin/composer + +ENTRYPOINT [] diff --git a/demo/Makefile b/demo/Makefile new file mode 100644 index 0000000..14c0aea --- /dev/null +++ b/demo/Makefile @@ -0,0 +1,38 @@ +# Records the demo of the README and the social preview in Docker: no local +# PHP and no VHS needed. `make -C demo all` from the root of the package. + +.DEFAULT_GOAL := help + +ROOT := $(abspath $(CURDIR)/..) +IMAGE := phpunit-pest-html-assertions-demo +# As the user of the host: files the container writes stay the user's on Linux too. +RUN := docker run --rm --user $(shell id -u):$(shell id -g) -e HOME=/tmp -v "$(ROOT):/app" -w /app $(IMAGE) + +.PHONY: help build install preflight gif png all clean + +help: ## Show the targets + @grep -E '^[a-z]+:.*## ' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*## "}; {printf " %-10s %s\n", $$1, $$2}' + +build: ## Build the image: VHS with PHP and Composer + docker build -q -t $(IMAGE) $(CURDIR) + +install: build ## Install the demo app, with the package from this checkout + $(RUN) sh -c 'cd demo/app && rm -rf vendor composer.lock && composer install --no-interaction --no-progress -q' + +preflight: install ## Check that both scenes show what the recording expects + $(RUN) sh -c 'cd demo/app && vendor/bin/phpstan analyse --no-progress --error-format=json | grep -q "html.markupAsString"' + $(RUN) sh -c 'cd demo/app && vendor/bin/pest --colors=never tests/CartTest.php | grep -q "at tests/CartTest.php"' + $(RUN) sh -c 'cd demo/app && ! vendor/bin/pest --colors=never tests/CartTest.php | grep -q "src/PHPUnit/"' + +gif: preflight ## Record output/demo.gif + mkdir -p output + $(RUN) vhs demo/demo.tape + +png: preflight ## Record output/social.png + mkdir -p output + $(RUN) vhs demo/social.tape + +all: gif png ## Record both + +clean: ## Remove the installed demo app + rm -rf app/vendor app/composer.lock app/.phpstan diff --git a/demo/app/cart.php b/demo/app/cart.php new file mode 100644 index 0000000..d40e281 --- /dev/null +++ b/demo/app/cart.php @@ -0,0 +1,18 @@ + +

Your cart

+
    +
  • Apple
  • +
  • Pear
  • +
+

42.00 EUR

+ + HTML; +} diff --git a/demo/app/composer.json b/demo/app/composer.json new file mode 100644 index 0000000..67dd3e9 --- /dev/null +++ b/demo/app/composer.json @@ -0,0 +1,24 @@ +{ + "name": "demo/cart", + "description": "The app the demo of sorge-it/phpunit-pest-html-assertions runs.", + "license": "MIT", + "require-dev": { + "pestphp/pest": "^4.7|^5.0", + "phpstan/phpstan": "^2.2", + "sorge-it/phpunit-pest-html-assertions": "*@dev" + }, + "repositories": [ + { + "type": "path", + "url": "../.." + } + ], + "autoload": { + "files": ["cart.php"] + }, + "config": { + "allow-plugins": { + "pestphp/pest-plugin": true + } + } +} diff --git a/demo/app/phpstan.neon b/demo/app/phpstan.neon new file mode 100644 index 0000000..e2a816b --- /dev/null +++ b/demo/app/phpstan.neon @@ -0,0 +1,9 @@ +# Level 0: PHPStan knows neither the expectations Pest adds nor its higher-order chain. +includes: + - vendor/sorge-it/phpunit-pest-html-assertions/extension.neon + +parameters: + level: 0 + paths: + - tests + tmpDir: .phpstan diff --git a/demo/app/phpunit.xml b/demo/app/phpunit.xml new file mode 100644 index 0000000..0c77903 --- /dev/null +++ b/demo/app/phpunit.xml @@ -0,0 +1,11 @@ + + + + + tests + + + diff --git a/demo/app/social.php b/demo/app/social.php new file mode 100644 index 0000000..8c72092 --- /dev/null +++ b/demo/app/social.php @@ -0,0 +1,23 @@ +within('[data-cart]') + ->toHaveSelectorText('[data-name="Pear"]', 'Pear, ripe', 'The shop sells ripe pears only.'); +}); diff --git a/demo/app/tests/StringTest.php b/demo/app/tests/StringTest.php new file mode 100644 index 0000000..53bba80 --- /dev/null +++ b/demo/app/tests/StringTest.php @@ -0,0 +1,7 @@ +toContain('
  • Pear, ripe
  • '); +}); diff --git a/demo/demo.tape b/demo/demo.tape new file mode 100644 index 0000000..28afa64 --- /dev/null +++ b/demo/demo.tape @@ -0,0 +1,37 @@ +# The animated demo in the README: PHPStan reports a check of markup as a +# string, the check by selector fails and names the region. +# Run through `make -C demo gif`; https://github.com/charmbracelet/vhs + +Output demo/output/demo.gif + +Set Shell bash +Set Width 1280 +Set Height 940 +Set FontSize 16 +Set Theme "Catppuccin Mocha" +Set Padding 24 +Set Framerate 24 +Set TypingSpeed 35ms +Set CursorBlink false + +Hide +Type "cd demo/app && export PS1='$ ' && clear" +Enter +Show + +Sleep 800ms +Type "cat tests/StringTest.php" +Enter +Sleep 2s +Type "vendor/bin/phpstan analyse --no-progress" +Enter +Sleep 6s + +Type "clear" +Enter +Type "cat tests/CartTest.php" +Enter +Sleep 2.5s +Type "vendor/bin/pest tests/CartTest.php" +Enter +Sleep 9s diff --git a/demo/output/demo.gif b/demo/output/demo.gif new file mode 100644 index 0000000..0e62239 Binary files /dev/null and b/demo/output/demo.gif differ diff --git a/demo/output/social.png b/demo/output/social.png new file mode 100644 index 0000000..629ded8 Binary files /dev/null and b/demo/output/social.png differ diff --git a/demo/social.tape b/demo/social.tape new file mode 100644 index 0000000..a8d572c --- /dev/null +++ b/demo/social.tape @@ -0,0 +1,19 @@ +# The social preview of the GitHub repository: the name and one failure, 1280 × 640. +# Run through `make -C demo png`; https://github.com/charmbracelet/vhs + +Set Shell bash +Set Width 1280 +Set Height 640 +Set FontSize 14 +Set Theme "Catppuccin Mocha" +Set Padding 28 +Set CursorBlink false + +Hide +Type "cd demo/app && export PS1='$ ' && php social.php" +Enter +Sleep 6s +Show +Sleep 500ms + +Screenshot demo/output/social.png diff --git a/resources/boost/guidelines/core.blade.php b/resources/boost/guidelines/core.blade.php new file mode 100644 index 0000000..7079bb4 --- /dev/null +++ b/resources/boost/guidelines/core.blade.php @@ -0,0 +1,9 @@ +## sorge-it/phpunit-pest-html-assertions + +- Check rendered HTML (a response, a view, a component, a Livewire test, a string of markup) with CSS selectors, never as a string: no `assertSee`, `assertSeeHtml`, `toContain('<…')`, `str_contains()` or regular expression over markup. +- Pest: `expect($response)->toHaveSelectorText('[data-total]', '42.00 EUR')`. PHPUnit: the trait `SorgeIt\PhpunitPestHtmlAssertions\PHPUnit\AssertsHtml`, `self::assertHtmlSelectorTextSame($response, '[data-total]', '42.00 EUR')`. +- Select by tag, role, `aria-*`, label or text, then by a `data-*` marker. A class is a value to check with `toHaveSelectorClass()`, not a selector. +- A check of one node needs exactly one match. Narrow to a region with `expect(html($page))->within('[data-cart]')`; `html()` is the function `SorgeIt\PhpunitPestHtmlAssertions\Pest\html`. +- Give a check its reason as the last argument: the failure message shows it first. After the optional value of `toHaveSelectorAttribute()`, pass it by name: `message: '…'`. +- The PHPStan rules `html.markupAsString` and `html.classAsString` report a check of markup or of a class as a string. Rewrite the check; ignore a line only with a reason. +- Read the skill `phpunit-pest-html-assertions` before you write or change such a test. diff --git a/resources/boost/skills/phpunit-pest-html-assertions/SKILL.md b/resources/boost/skills/phpunit-pest-html-assertions/SKILL.md index c70c109..6630a05 100644 --- a/resources/boost/skills/phpunit-pest-html-assertions/SKILL.md +++ b/resources/boost/skills/phpunit-pest-html-assertions/SKILL.md @@ -12,7 +12,7 @@ metadata: - Check HTML through the DOM with a CSS selector. Never compare markup as a string: no `assertSee`, `assertSeeHtml`, `toContain('x` in ``. - Escape a colon or a dot in an attribute name: `[wire\:model="name"]`. @@ -108,6 +108,12 @@ A region reads like `querySelectorAll`: it finds nodes below its element, not th In plain PHP: `Html::of($value)->within($selector)`, `->frame()`, `->matches()`, `->texts()`, `->rawTexts()`, `->attributes()`, `->attributeValues()`, `->count()`, `->text()`. +## When a check fails + +The message names the path of regions, for example `(page) > [data-cart]`, then what was asked and what was found. Below follows the HTML of the region, cut at 40 lines. Read it to fix the test or the view; no browser is needed. + +A failure points at the line of the test; the trace leaves out the frames of this package. To see them, for example to report a bug in the package, run the test with `HTML_ASSERTIONS_SHOW_FRAMES=1` set in the shell, not in `phpunit.xml`. + ## Text Text is compared with white space collapsed and trimmed. The text of a `script`, `style`, `template`, `noscript` or `head` inside the node does not count. diff --git a/src/PHPUnit/Autoload.php b/src/PHPUnit/Autoload.php new file mode 100644 index 0000000..1114545 --- /dev/null +++ b/src/PHPUnit/Autoload.php @@ -0,0 +1,13 @@ + */ + private array $excluded; + + protected function setUp(): void + { + // Filled once, with PHPUnit's own directories: restored unfilled, it would stay empty. + $this->excluded = (new ExcludeList())->getExcludedDirectories(); + } + + protected function tearDown(): void + { + $this->directories()->setValue(null, $this->excluded); + } + + public function test_the_suite_of_the_package_runs_with_its_frames(): void + { + self::assertFalse((new ExcludeList())->isExcluded($this->package().'/src/PHPUnit/Assertion.php')); + } + + public function test_a_failure_in_another_project_points_at_the_test(): void + { + StackTrace::hide(sys_get_temp_dir(), false); + + $trace = Filter::stackTraceFromThrowableAsString($this->failure()); + + self::assertStringStartsWith(__FILE__.':', $trace); + self::assertStringNotContainsString($this->package().'/src/', $trace); + } + + public function test_a_root_without_a_real_path_counts_as_another_project(): void + { + StackTrace::hide('/no/such/project', false); + + self::assertStringStartsWith(__FILE__.':', Filter::stackTraceFromThrowableAsString($this->failure())); + } + + public function test_the_checkout_of_the_package_keeps_its_frames(): void + { + StackTrace::hide($this->package().'/tests/..', false); + + $trace = Filter::stackTraceFromThrowableAsString($this->failure()); + + self::assertStringStartsWith($this->package().'/src/PHPUnit/Assertion.php:', $trace); + } + + public function test_a_bug_report_keeps_the_frames_of_the_package(): void + { + StackTrace::hide(sys_get_temp_dir(), true); + + $trace = Filter::stackTraceFromThrowableAsString($this->failure()); + + self::assertStringStartsWith($this->package().'/src/PHPUnit/Assertion.php:', $trace); + } + + private function package(): string + { + return dirname(__DIR__, 2); + } + + private function failure(): ExpectationFailedException + { + try { + self::assertHtmlSelectorExists('

    ', '[data-missing]'); + } catch (ExpectationFailedException $expectationFailedException) { + return $expectationFailedException; + } + + self::fail('The check passed.'); + } + + private function directories(): ReflectionProperty + { + return new ReflectionProperty(ExcludeList::class, 'directories'); + } +}