add a way to manually use the test site from a Functional test

Could the MR be updated for 10.1 please.

Added control of this feature with a BROWSERTEST_PRESERVE_SITE env var, and added documentation to phpunit.xml.dist.

Sounds like a useful idea.

I usually have to look at screenshots in the pipeline to see what went wrong.

Reading the comments not 100% sure how to get it working but maybe the CR will help clear that up.

Let's have this documented in the wiki and the change record can just refer to that. I think this is the page, PHPUnit Browser test tutorial → .

Proposed documentation text:

Interacting with the test site

The test site can be preserved after the test has run, to allow the developer to interact with it as with a normal site and to inspect the database tables. This is useful for debugging and developing tests, when the HTML output files are insufficient to understand a problem.

To preserve a test site instead of having it be deleted in the test’s tear down phase, do one of the following:

• Set the class property $preserveSiteInTearDown to TRUE in your test class
• Set the environment variable BROWSERTEST_PRESERVE_SITE to ‘true’ on the command line when running phpunit
• Set the environment variable BROWSERTEST_PRESERVE_SITE to ‘true’ in your phpunit.xml file

Then, after the test has run, do the following:

1. Find the test site prefix. You can get this from the test site directory which was created during the test in your sites/ directory. It will be of the form ‘simpletest/test_123456'. The ‘test_123456’ is the test site prefix.
2. Set up the sites.php file if it is not already present.
3. Add code to return the test site directory as the site. The simplest way is to completely replace the main site with the test site:
   

   $sites = [
   ‘example.com’ => ‘simpletest/TEST_PREFIX',
   ];</ol>
   

You can then use your site as you would a normal Drupal site. The admin user login is ‘admin’/‘admin’.

You will need to delete the site directory and the test site database tables manually.

—————-

TODO: it occurs to me writing these instructions that it would be a nice DX touch to output the test site prefix in the phpunit output when the site is being preserved.

PS. It’s not a wiki!!!

Wrote CR & draft documentation.

Ready for review again.

Read the Cr and feel comfortable removing that tag.

Leaving the documentation tag as don't know the process for getting that page updated.

But thinks seem clearer based on what's there. Going to mark.

I have been wanting to test this and today I finally did. I am pleased to say that it works in my environment which is DDEV and with a separate database for testing.

TODO: it occurs to me writing these instructions that it would be a nice DX touch to output the test site prefix in the phpunit output when the site is being preserved.

Yes, that would be a nice to have.

The text in #14 for the doc page is fine with me. It does help to see it here though instead of waiting for this to be committed.

I left comments and suggestions in the MR, about the comments, that do need to be looked at.

> Yes, that would be a nice to have.

Done, but I suspect this is going to bog this issue down, as the way I've done it isn't ideal and I don't see a better way.

It's not ideal because printing from within the test process causes PHPUnit to say the test was risky because it printed something. I think that's acceptable, because the developer knows they're doing something for debugging.

I experimented with using a PHPUnit extension, same way that HtmlOutputLogger is a PHPUnit extension, but that doesn't work because outside of the test's process, we can't get the site ID.

The only way that I can think of would be to either write the ID to a file, or have the PHPUnit extension look at all the folders in sites/simpletest and pick the newest one.