Testing Factory
Mantle supports a WordPress-core backwards compatible factory that can be used in tests to quickly generate posts, terms, sites, and more.
The factory supports the creation of the following types of content:
- attachment
- category
- comment
- page
- post
- tag
- term
- user
- blog (if mulitisite)
- network (if multisite)
The testing factory used by the testing framework is the same factory used by Mantle's database factory.
For more information on the database factory, see the Database Factory documentation.
Generating Content
All factories function in the same manner and be used to generate one or many pieces of content:
use Mantle\Testkit\Test_Case as Testkit_Test_Case;
class ExampleTests extends Testkit_Test_Case {
public function test_factory() {
static::factory()->post->create_and_get(); // WP_Post
static::factory()->post->create(); // int
static::factory()->post->create_many( 10 ); // int[]
// Supports overriding attributes for a factory.
static::factory()->post->create( [ 'title' => 'Example Title' ] );
static::factory()->tag->create_and_get(); // WP_Term
static::factory()->tag->create(); // int
}
}
For more information on how to generate content with factories, see the Model Factory: Generated Content documentation.
Generating Blocks
Generating blocks is a common use case when testing WordPress sites that depend
on blocks in different contexts for testing. The block_factory()
method can be
used to generate blocks for testing:
use Mantle\Testkit\Test_Case as Testkit_Test_Case;
use function Mantle\Testing\block_factory;
class ExampleTests extends Testkit_Test_Case {
public function test_post_with_block() {
$post = static::factory()->post->create_and_get( [
'post_content' => block_factory()->blocks( [
block_factory()->heading( 'Example Heading' ),
block_factory()->paragraph( 'Example Paragraph' ),
] ),
] );
$block = block_factory()->create_block( 'core/paragraph' );
$this->assertNotEmpty( $block );
}
}
The Block Factory works with the Block Faker to make it possible to generate blocks in tests with ease.
Generating Paragraph Blocks
The Block Factory's paragraph
method can be used to generate a paragraph block
with the specified content or default lorem ipsum content:
use function Mantle\Testing\block_factory;
$block = block_factory()->paragraph();
Which would produce the following block:
<!-- wp:paragraph -->
<p>Dolores esse et quam dolores perspiciatis. Ut et et dolor voluptate quia ipsam distinctio. Saepe eum placeat dolor saepe ut cum officia.</p>
<!-- /wp:paragraph -->
The text can be overridden by passing a string to the paragraph
method:
use function Mantle\Testing\block_factory;
$block = block_factory()->paragraph( 'Example Paragraph' );
Which would produce the following block:
<!-- wp:paragraph -->
<p>Example Paragraph</p>
<!-- /wp:paragraph -->
You can also specify the number of sentences to generate for the paragraph:
use function Mantle\Testing\block_factory;
$block = block_factory()->paragraph( sentences: 5 );
Generating Multiple Paragraph Blocks
The Block Factory's paragraphs
method can be used to generate multiple
paragraph blocks with the specified content or default lorem ipsum content:
use function Mantle\Testing\block_factory;
$blocks = block_factory()->paragraphs( 3 );
Generating Heading Blocks
The Block Factory's heading
method can be used to generate a heading block
with the specified content or default lorem ipsum content:
use function Mantle\Testing\block_factory;
$block = block_factory()->heading();
Which would produce the following block:
<!-- wp:heading -->
<h2>Dolores esse et quam dolores perspiciatis.</h2>
<!-- /wp:heading -->
The text can be overridden by passing a string to the heading
method:
use function Mantle\Testing\block_factory;
$block = block_factory()->heading( 'Example Heading' );
Which would produce the following block:
<!-- wp:heading -->
<h2>Example Heading</h2>
<!-- /wp:heading -->
You can also specify the heading level to generate:
use function Mantle\Testing\block_factory;
$block = block_factory()->heading( level: 3 );
Generating Image Blocks
The Block Factory's image
method can be used to generate an image block with
a default image from picsum.photos:
use function Mantle\Testing\block_factory;
$block = block_factory()->image();
Which would produce the following block:
<!-- wp:image -->
<figure class="wp-block-image"><img src="https://picsum.photos/620/383"/></figure>
<!-- /wp:image -->
Generating a Custom Block
The Block Factory's block
method can be used to generate a custom block
with the specified block name and attributes:
use function Mantle\Testing\block_factory;
$block = block_factory()->block(
'vendor/block-name',
'Inner content (if any).',
[
'attribute' => 'value',
],
);
Generating Sets of Blocks
The Block Factory's blocks
method can be used to generate a set of blocks:
use function Mantle\Testing\block_factory;
$blocks = block_factory()->blocks( [
block_factory()->heading( 'Example Heading' ),
block_factory()->paragraph( 'Example Paragraph' ),
] );
Which would produce the following blocks:
<!-- wp:heading {"level":2} -->
<h2>Example Heading</h2>
<!-- /wp:heading -->
<!-- wp:paragraph -->
<p>Example Paragraph</p>
<!-- /wp:paragraph -->
Using Block Presets
Block presets can be used to generate blocks with a specific set of attributes. This can be useful when a project has a common set of blocks that are used across multiple tests. For example, a media website may have a post with a common template of a custom block, a heading, and a paragraph. A block preset can be created to generate this set of blocks:
use Mantle\Testing\Block_Factory;
Block_Factory::register_preset(
'article_3_up',
block_factory()->blocks( [
block_factory()->block( 'vendor/block-name', '', [
'attribute' => 'value',
] ),
block_factory()->heading(),
block_factory()->paragraph(),
] ),
);
The block preset can then be used in tests:
use function Mantle\Testing\block_factory;
$blocks = block_factory()->preset( 'article_3_up' );
// You can also use a magic method to call it directly.
$blocks = block_factory()->article_3_up();
Presets can also be a callable function that returns a set of blocks. The callable will be passed an instance of the Block Factory:
use Mantle\Testing\Block_Factory;
Block_Factory::register_preset(
'content_with_video',
fn ( Block_Factory $factory ) => $factory->blocks( [
$factory->block( 'vendor/block-name', '', [
'attribute' => 'value',
] ),
$factory->heading(),
$factory->paragraph(),
] ),
);