Update readme: Testing section by gRegorLove · Pull Request #282 · microformats/php-mf2

gRegorLove · 2026-06-25T22:49:00Z

Current instructions based on composer.json scripts and #163

jtojnar

Here is a bit nitpicky dump of a heat wave liquefied brain, sorry.

jtojnar · 2026-06-26T18:37:41Z

+The php-mf2 tests are in `/tests/Mf2` and contain many parsing examples, internal parser tests, and regression tests for specific issues over php-mf2’s history. If you do not have a live internet connection, you can exclude tests that depend on it by running `composer tests-no-internet`

-Currently php-mf2 passes the majority of it’s own test case, and a good percentage of the cross-platform tests. Contributors should ALWAYS test against the PHPUnit suite to ensure any changes don’t negatively impact php-mf2, and SHOULD run the cross-platform suite, especially if you’re changing parsing behaviour.
+The other test suite is the cross-platform [microformats/tests](https://github.com/microformats/tests). This has backwards-compatible tests for microformats1, some of which php-mf2 will fail, so it does not automatically run them currently. To run these tests, first run `composer install`, then run `composer microformats-test-mf1`. There are additional composer scripts listed below for running other parts of this test suite.


Running composer install is required for all tests since it installs phpunit.

jtojnar · 2026-06-27T11:44:24Z

+The php-mf2 tests are in `/tests/Mf2` and contain many parsing examples, internal parser tests, and regression tests for specific issues over php-mf2’s history. If you do not have a live internet connection, you can exclude tests that depend on it by running `composer tests-no-internet`

-Currently php-mf2 passes the majority of it’s own test case, and a good percentage of the cross-platform tests. Contributors should ALWAYS test against the PHPUnit suite to ensure any changes don’t negatively impact php-mf2, and SHOULD run the cross-platform suite, especially if you’re changing parsing behaviour.
+The other test suite is the cross-platform [microformats/tests](https://github.com/microformats/tests). This has backwards-compatible tests for microformats1, some of which php-mf2 will fail, so it does not automatically run them currently. To run these tests, first run `composer install`, then run `composer microformats-test-mf1`. There are additional composer scripts listed below for running other parts of this test suite.


I think this makes it sound too much like the mf1 is the only thing this repo contains.

jtojnar · 2026-06-27T11:47:01Z


+Currently php-mf2 passes its own test cases and a good percentage of the cross-platform tests. Contributors MUST always test against the PHPUnit suite to ensure any changes don’t negatively impact php-mf2, and SHOULD run the cross-platform suite, especially if you’re changing parsing behaviour.
+
+**Composer scripts**


We might want to use script-descriptions in composer.json instead:

https://getcomposer.org/doc/articles/scripts.md#custom-descriptions

jtojnar · 2026-06-27T11:50:50Z

-Currently php-mf2 passes the majority of it’s own test case, and a good percentage of the cross-platform tests. Contributors should ALWAYS test against the PHPUnit suite to ensure any changes don’t negatively impact php-mf2, and SHOULD run the cross-platform suite, especially if you’re changing parsing behaviour.
+The other test suite is the cross-platform [microformats/tests](https://github.com/microformats/tests). This has backwards-compatible tests for microformats1, some of which php-mf2 will fail, so it does not automatically run them currently. To run these tests, first run `composer install`, then run `composer microformats-test-mf1`. There are additional composer scripts listed below for running other parts of this test suite.

+Currently php-mf2 passes its own test cases and a good percentage of the cross-platform tests. Contributors MUST always test against the PHPUnit suite to ensure any changes don’t negatively impact php-mf2, and SHOULD run the cross-platform suite, especially if you’re changing parsing behaviour.


It passes all cross-platform tests except for about half (17/39) of the mf1 ones. “Good percentage” undersells it IMO.

jtojnar · 2026-06-27T12:18:45Z

-Currently php-mf2 passes the majority of it’s own test case, and a good percentage of the cross-platform tests. Contributors should ALWAYS test against the PHPUnit suite to ensure any changes don’t negatively impact php-mf2, and SHOULD run the cross-platform suite, especially if you’re changing parsing behaviour.
+The other test suite is the cross-platform [microformats/tests](https://github.com/microformats/tests). This has backwards-compatible tests for microformats1, some of which php-mf2 will fail, so it does not automatically run them currently. To run these tests, first run `composer install`, then run `composer microformats-test-mf1`. There are additional composer scripts listed below for running other parts of this test suite.

+Currently php-mf2 passes its own test cases and a good percentage of the cross-platform tests. Contributors MUST always test against the PHPUnit suite to ensure any changes don’t negatively impact php-mf2, and SHOULD run the cross-platform suite, especially if you’re changing parsing behaviour.


I do not like that we now have two places with instructions. It feels redundant, especially when CI enforces it.

I'm not sure what you mean, where's the second place?

jtojnar · 2026-06-27T12:19:48Z

+There are two test suites described in more detail below. At a minimum, you should run `composer check-and-tests`, which will run `phpcs`, php-mf2 tests, and microformats/tests (except mf1).

-The other, in `tests/test-suite`, is a custom test harness which hooks up php-mf2 to the cross-platform [microformats test suite](https://github.com/microformats/tests). To run these tests you must first install the tests with `./composer.phar install`. Each test consists of a HTML file and a corresponding JSON file, and the suite can be run with `php ./tests/test-suite/test-suite.php`.
+The php-mf2 tests are in `/tests/Mf2` and contain many parsing examples, internal parser tests, and regression tests for specific issues over php-mf2’s history. If you do not have a live internet connection, you can exclude tests that depend on it by running `composer tests-no-internet`


tests are in /tests/Mf2

Turns out the cross-platform ones have entry point there as well. Not sure how to reformulate it, though.

I believe it's the only entry point. microformats/tests is a set of HTML and expected JSON outputs, not a set of unit tests, so php-mf2 has to build the unit tests in MicroformatsTestSuiteTest.php

jtojnar · 2026-06-27T12:36:51Z

+  - same, but exclude tests that require internet: `composer tests-no-internet`
+- microformats/tests suite:
+	- run mf1 tests with `composer microformats-tests-mf1`
+	- run mf2 tests with `composer microformats-tests-mf2`


Actually, thinking about it some more, do we even need an explicit command to run all these different subsets?

But when working on the codebase, a developer probably either wants to run all tests to check they did not introduce a regression, or a specific one, for which we will not be able to have a composer script anyway and they will have to use something like composer tests -- --filter hcard (but that's what PHPUnit docs are for).

This matches what we had previously – we only introduced scripts as needed due to external circumstances like network not being available or stuff not being implemented.

I would even go as far and drop the separate tests-mf1 script to simplify this as much as possible: #284

Heh, I added those two because you suggested them. :)

It is a goal for php-mf2 to pass all of the backcompat tests in microformats/tests. When we introduced that test suite, it failed a large portion of them, so we chose to exclude them from the default test run. We still want a way to run them, thus the extra script.

jtojnar · 2026-06-27T12:37:50Z

 * All content apart from the 'html' key in dictionaries produced by parsing an `e-*` property is not HTML-escaped. For example, `<span class="p-name">&lt;code&gt;</span>` will result in `"name": ["<code>"]`. At the very least, HTML-escape all properties before echoing them out in HTML
 * If you’re using the raw HTML content under the 'html' key of dictionaries produced by parsing `e-*` properties, you SHOULD purify the HTML before displaying it to prevent injection of arbitrary code. For PHP we recommend using [HTML Purifier](http://htmlpurifier.org)

 ## Contributing


A bit unrelated, I also wonder if we should not move this to CONTRIBUTING.md:

https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors

Co-authored-by: Jan Tojnar <jtojnar@gmail.com>

Update readme: Testing section

8185039

gRegorLove added this to the 0.5.1 milestone Jun 25, 2026

jtojnar reviewed Jun 25, 2026

View reviewed changes

Comment thread README.md Outdated

jtojnar reviewed Jun 26, 2026

View reviewed changes

Comment thread README.md Outdated

Update composer scripts and readme

63a4f3a

gRegorLove requested a review from jtojnar June 26, 2026 18:03

jtojnar reviewed Jun 27, 2026

View reviewed changes

Update composer.json

924f19c

Co-authored-by: Jan Tojnar <jtojnar@gmail.com>


		Currently php-mf2 passes its own test cases and a good percentage of the cross-platform tests. Contributors MUST always test against the PHPUnit suite to ensure any changes don’t negatively impact php-mf2, and SHOULD run the cross-platform suite, especially if you’re changing parsing behaviour.

		Composer scripts

Uh oh!

Conversation

gRegorLove commented Jun 25, 2026

Uh oh!

Uh oh!

Uh oh!

jtojnar left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants