Add built-in command for selecting the editor canvas when it is iframed

[Joe-Rouse]

Is your feature request related to a problem? Please describe.

On WordPress 6.3 and above, the editor canvas can be iframed if there are no blocks registered with an API version lower than 3. In a future version of WordPress this will be standard no matter what blocks are registered. More info on this can be found here: https://make.wordpress.org/core/2023/07/18/miscellaneous-editor-changes-in-wordpress-6-3/#post-editor-iframed

This makes it harder as any selectors that try and get elements within the editor canvas don't work as you'd expect as they are now inside an iframe.

Describe the solution you'd like

There have been a few projects that implement the workaround documented in this Cypress blog post.

For example, on NewsPress' text only mode plugin:

const getIframeDocument = () => {
	return (
		cy
			.get( 'iframe[name="editor-canvas"]' )
			.its( '0.contentDocument' )
			.should( 'exist' )
	);
};

Cypress.Commands.add( 'getIframe', () => {
	return (
		getIframeDocument()
			.its( 'body' )
			.should( 'not.be.undefined' )
			.then( cy.wrap )
	);
} );

Cypress.Commands.add( 'getIntroParagraph', () => {
	return cy.getIframe().find( '.textOnly_content-intro' );
} );

It would be handy to have this as a command provided by the wp-cypress plugin to save having to add and maintain this across all projects that need it.

Describe alternatives you've considered

N/A

Additional context

N/A

[g-elwell]

+1, it would be great to abstract this as a built-in command as people will begin to hit this issue more and more.

My implementation of a solution was taken from the same blog post you linked to in your OP, which mentions that combining the its commands into a single command will ensure that the selector is re-tried should the page re-render during a test. Otherwise, you can encounter an issue where the iFrame reference is no longer valid:

/**
 * Custom command to select the block editor iframe
 *
 * @example cy.getBlockEditor().find('.editor-post-title__input').type('Edit 1');
 * @see https://www.cypress.io/blog/2020/02/12/working-with-iframes-in-cypress
 */
Cypress.Commands.add('getBlockEditor', () => {
  return cy
    .get('iframe[name="editor-canvas"]')
    .its('0.contentDocument.body')
    .should('not.be.empty')
    .then(cy.wrap);
});

There is also the cypress-iframe package which may be worth looking into, but even if we used that package I feel a custom command for WP Cypress would be beneficial to shorten:

cy.iframe('iframe[name="editor-canvas"]').find('.some-button').should('be.visible').click()

to:

cy.blockEditor().find('.some-button').should('be.visible').click()