Command/40 Added checkBlockPatternExists command.

[faisal-alvi]

Description of the Change

Added a new command checkBlockPatternExists which checks whether a given pattern exists on the site or not.

It accepts the following parameters.

• title: Pattern name/title.
• categoryValue: Value of the pattern category. for example "twentytwentyone" for the Twenty Twenty-One category.

Closes #40

Verification Process

1. Build the project using npm run build.
2. Make sure the docker is running.
3. Run npm run env:start.
4. Run npm run cypress:open.
5. Run check-block-pattern-exists.test.js.
6. Try to change the pattern name and its category in the /tests/cypress/integration/check-block-pattern-exists.test.js file and see the test results.

Checklist:

• I have read the CONTRIBUTING document.
• My code follows the code style of this project.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have added tests to cover my change.
• All new and existing tests passed.

Changelog Entry

Added - New Command checkBlockPatternExists to check if block pattern exists.

Credits

Props @faisal-alvi

[cadic]

@faisal-alvi thank you for the great tool. I left few comments to the code.

It also seems to me that command name and/or the work it does is not accurate. The command will insert the block pattern if it finds it, while from its name we expect just the check of existence.

In case we just want to check if block pattern exists, maybe it's better to finish the procedure with wrapping the result. It will allow to chain and tester will decide if they want to insert the pattern:

cy
  .checkBlockPatternExists({title:'Title', categoryValue:'cat'})
  .then((exists) => {
    if(exists) {
      // insert pattern
    } else {
      // alternative test workflow
    }
  });

Please refer to createTerm command and it's tests to see how it works

[cadic]

Could you please update this to use closeWelcomeGuide command

[cadic]

A typo here?

[cadic]

Using {force: true} brings a potentially false positive workflow to the test process. In case if the element is hidden, the command will click it anyway, while regular users could not do that.

While this behaviour is ok for testing end-products, but it's not welcomed within the library. @dinhtungdu, need your opinion on this please.

[dinhtungdu]

While this behaviour is ok for testing end-products, but it's not welcomed within the library.

@cadic I agree. Using click with force set to true will bypass actionability checks. In the other words, a hidden element can be clickable. It doesn't replicate human behavior so we should avoid that when possible.

[dinhtungdu]

It also seems to me that command name and/or the work it does is not accurate. The command will insert the block pattern if it finds it, while from its name we expect just the check of existence.

I have the same thought. Besides, I think it's developer's responsibility to ensure the patterns exist before inserting. So we just need a command to simply insert a pattern to the page. If the pattern doesn't exist for any reason:

• That's the potential issue of the plugin and should be fixed in the plugin source code.
• Or that can be an issue with the test environment, which also shouldn't be covered by this library but the environment config instead.

[faisal-alvi]

The cypress checks for the pattern but when we switch the category as shown in the below screenshot, the patterns render slowly (replaces is-placeholder divs one-by-one) and cause the test to fail. Tried using setInterval but that does not work well. Finally, as a workaround, added 10s of waiting time to allow WordPress to render patterns.

Please share if there is a better solution.

[Sidsector9]

If the sole purpose of this command is to check whether a pattern exists or not, rather than going through the UI, can we use code instead?

Something like this:

cy.window().then( win => {
    const { wp } = win;

    const { getSettings } = wp.data.select( 'core/block-editor' );
    const allRegisteredPatterns = getSettings().__experimentalBlockPatterns;

    /**
     * loop through all the patterns to check if pattern exists
     */
} );

[Sidsector9]

The function can be reduced to:

/* eslint-disable tsdoc/syntax */
/**
 * Check Block Pattern Exists. Works only with WordPress \>=5.5
 *
 * \@param postData {
 *          `title` - Patttern name/title,
 *          `categoryValue` - Value of the pattern category,
 *        }
 *
 * @example
 * For WP v5.5
 * ```
 * cy.checkBlockPatternExists({
 *    title: 'Two buttons',
 * });
 * ```
 *
 * @example
 * For WP v5.9
 * ```
 * cy.checkBlockPatternExists({
 *    title: 'Three columns with offset images',
 *    categoryValue: 'gallery',
 * });
 * ```
 */
export const checkBlockPatternExists = ({
  title,
  categoryValue = 'featured',
}: {
  title: string;
  categoryValue?: string;
}): void => {
  cy.visit('/wp-admin/post-new.php');

  // Close Welcome Guide.
  cy.closeWelcomeGuide();

  cy.window().then( win => {
    const { wp } = win;

    const { getSettings } = wp.data.select( 'core/block-editor' );
    const allRegisteredPatterns = getSettings().__experimentalBlockPatterns;

    for ( let i = 0; i < allRegisteredPatterns.length; i++ ) {
      if ( title === allRegisteredPatterns[i].title && allRegisteredPatterns[i].categories && allRegisteredPatterns[i].categories.includes(categoryValue) ) {
        cy.wrap(true);
        return;
      }
    }

    cy.wrap(false);
  });
};

[faisal-alvi]

@Sidsector9 this is what I was thinking about but as the Cypress is an E2E test, I thought to stick with the UI.

I've checked the code and it works in old and new WP versions, however, while building the project, the following error is displayed:

[Sidsector9]

@faisal-alvi I haven't looked through the project entirely, but adding the following at the top of your file should work:

declare global {
  interface Window {
    wp: any;
  }
}

this is what I was thinking about but as the Cypress is an E2E test, I thought to stick with the UI.

While you're correct to do so, one important thing to consider is that these utilities are not meant for testing Gutenberg itself. They're helpers to test "things" built using Gutenberg's features. Keeping this in mind, going the UI/non-UI way doesn't make much of a difference. @dinhtungdu, any thoughts on this?

[dinhtungdu]

@faisal-alvi Can you please check and fix the canceled workflows here?

I agree with Sid that this doesn't make much difference for this command even in the E2E context.

[cadic]

@dinhtungdu looks like all 3 workflows were cancelled by timeout after 6 hours of being stuck

[faisal-alvi]

The Github actions behave weirdly sometimes. I have tested in a local for WP 5.9 and the tests are passing:

Any feedback from anyone? or are we good to go for merge?

[dinhtungdu]

@faisal-alvi alert() requires human interaction to close the alert which never happens in the CI environments. I believe this causes the tests to be stuck.

[faisal-alvi]

Awesome @dinhtungdu !!

[cadic]

@faisal-alvi I've updated the test and checked the command against every WP core since 5.2

You can use run-all-cores.sh script for that:

./run-all-cores.sh -s tests/cypress/integration/check-block-pattern-exists.test.js

• for WP 5.5 and 5.6 using "name only" command call from your example in the command declaration
• for WP 5.7+ using extended attribute with block category name

const args = {
  title: testCase.title,
};

if (compare(Cypress.env('WORDPRESS_CORE').toString(), '5.7', '>=')) {
  args.categoryValue = testCase.cat;
}

WordPress core	Test
5.2	⏭ Skip
5.3	⏭ Skip
5.4	⏭ Skip
5.5	❌ Fail
5.6	❌ Fail
5.7	✅ Pass
5.8	✅ Pass
5.9	✅ Pass
6.0	❌ Fail
6.1	❌ Fail

In WP 5.5 and 5.6 Block patterns were in very early stage, I believe we could skip supporting this command for very old versions.

But support of WP 6.0+ is important. Could it be related to __experimentalBlockPatterns?

const allRegisteredPatterns = getSettings().__experimentalBlockPatterns;

[Sidsector9]

@cadic I fixed the tests for WP 6.0+. I think 6.0 takes time or maybe defers loading of block patterns.

@faisal-alvi I've made a minor change. I have moved cy.visit() and cy.closeWelcomeGuide() functions outside of checkBlockPatternExists as this function should only deal with identifying patterns. Navigation and other aspects should be handled by the test.

Another reason is that if we use checkBlockPatternExists multiple times in the same test for a post, it will navigate to a new post.

[faisal-alvi]

@Sidsector9 makes sense. However, is it fine to use cy.wait(1000);? Isn't there any alternate? End users might not know to add a wait function before using checkBlockPatternExists.

[cadic]

@Sidsector9 I wonder why do we need this? Tests run successfully without this wait on my local environment. Maybe there is GitHub-related issue?

[Sidsector9]

@cadic same here. Works well locally but fails on Actions. That is what fixed the issue with WP6.0

[faisal-alvi]

@cadic @Sidsector9 any further updates here? Eager to see this merged!

[cadic]

Failed test is related to another command createTerm, please ignore

[Sidsector9]

@faisal-alvi @cadic I have removed the wait command, can you check?

[faisal-alvi]

@Sidsector9 @cadic I've tried to test this PR, the Cypress is throwing this error:

[Sidsector9]

@faisal-alvi that's expected to fail on local as we're only setting the environment variables when the actions are run.
If you want to run locally then you'll have to define it manually, such as:

CYPRESS_WORDPRESS_CORE=5.8 npm run cypress:run

[faisal-alvi]

I have merged the trunk here and it seems like the E2E Cypress tests failing for the other 3 tests that are not related to this PR. The one that is related to this PR, check-block-pattern-exists.test.js ran successfully. I would recommend that we go ahead and merge this one. Please share your thoughts @Sidsector9 @cadic

[cadic]

Thank you @faisal-alvi, this has been waiting for too long, finally LGTM 🔥