Skip to content
This repository was archived by the owner on Nov 19, 2024. It is now read-only.

Commit bde3bfe

Browse files
jeff-matthewsjeff-matthews
authored
Merge pull request magento-commerce/devdocs#2714 from magento-devdocs/imported-magento-l3-devdocs-9273
Imported magento l3 devdocs 9273
2 parents 9dbfab0 + ad816f5 commit bde3bfe

File tree

5 files changed

+326
-5
lines changed

5 files changed

+326
-5
lines changed

‎src/_data/toc/testing.yml

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,9 +34,17 @@ pages:
3434
- label: '@magentoDataFixture'
3535
url: /test/integration/annotations/magento-data-fixture.html
3636

37+
- label: '@magentoDataFixtureDataProvider'
38+
url: /test/integration/annotations/magento-data-fixture-data-provider.html
39+
exclude_versions: ["2.3"]
40+
3741
- label: '@magentoDbIsolation'
3842
url: /test/integration/annotations/magento-db-isolation.html
3943

44+
- label: Parameterized Data Fixture
45+
url: /test/integration/parameterized_data_fixture.html
46+
exclude_versions: ["2.3"]
47+
4048
- label: JavaScript Unit Testing
4149
children:
4250

‎src/guides/v2.4/test/integration/annotations.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,8 +16,9 @@ Admin Configuration Fixture|`@magentoAdminConfigFixture`|`@magentoAdminConfigFix
1616
Application Isolation|`@magentoAppIsolation`|`@magentoAppIsolation enabled|disabled`|Enables or disables application isolation when you run tests. When enabled, an application state after a test run will be the same as before the test run. For example, you should enable it, when you want to create sessions in a test, but you don't want them to affect other tests.
1717
Configuration Fixture|`@magentoConfigFixture`|`@magentoConfigFixture [<store_code>_store] <config_path> <config_value>`|Sets up configuration settings for a particular test. The list of settings is stored in the `core_config_data` database table. After the test execution, the settings revert to their original state.
1818
Database Isolation|`@magentoDbIsolation`|`@magentoDbIsolation enabled|disabled`|Enables or disables database isolation. Disabled by default, unless you are using `@magentoDataFixture`, in which case it is enabled by default. All data, required for a test, live during transaction only. Any test results won't be written in a database.
19-
Data Fixture|`@magentoDataFixture`|`@magentoDataFixture <script_filename>|<method_name>`|Points to a class or a method which creates testing entities (fixtures) for test execution. These are applied during the transaction.
19+
Data Fixture|`@magentoDataFixture`|`@magentoDataFixture <script_filename>|<method_name>|<fully_qualified_class_name> [as:alias | with:{}]`|Points to a class or a method which creates testing entities (fixtures) for test execution. These are applied during the transaction.
2020
Data Fixture Before Transaction|`@magentoDataFixtureBeforeTransaction`|`@magentoDataFixtureBeforeTransaction <script_filename>|<method_name>`|Points to a class or a method which creates testing entities (fixtures) for test execution before the transaction has begun. You will need to implement a rollback file for changes made here. (e.g. Fixture file my_fixture.php would also require a my_fixture_rollback.php that reverts the original fixture's changed.)
21+
Data Fixture Data Provider|`@magentoDataFixtureDataProvider`|`@magentoDataFixtureDataProvider <callable>|{}`|Points to a Data Provider callable method or contains an inline JSON string for Parameterized Data Fixtures.
2122
Application Area|`@magentoAppArea`|`@magentoAppArea adminhtml|frontend|global`|Configures test environment in the context of specified application area.
2223
Enable/Disable Cache|`@magentoCache`|`@magentoCache <type>|all enabled|disabled`|Enables or disables certain cache segment or all of them to prevent isolation problems.
2324
Indexer Dimension Mode|`@magentoIndexerDimensionMode`|`@magentoIndexerDimensionMode <indexer> <mode>`|Sets the indexer dimension mode for the test run. More information can be found in the [DevBlog](https://community.magento.com/t5/Magento-DevBlog/Indexers-parallelization-and-optimization/ba-p/104922).
@@ -30,6 +31,7 @@ The Magento-specific annotations for integration tests are applied in the follow
3031
1. `@magentoAppIsolation`
3132
1. `@magentoDbIsolation`
3233
1. `@magentoDataFixtureBeforeTransaction`
34+
1. `@magentoDataFixtureDataProvider`
3335
1. `@magentoDataFixture`
3436
1. `@magentoIndexerDimensionMode`
3537
1. `@magentoComponentsDir`

‎src/guides/v2.4/test/integration/annotations/magento-data-fixture-data-provider.md

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
---
2+
group: testing
3+
title: Data fixture data provider annotation
4+
---
5+
6+
{:.bs-callout-info}
7+
Data Fixture Data Provider is only applicable to Parameterized Data Fixture and is currently only available for Magento Open Source contributors. It will be released for general use with Magento Open Source 2.4.5.
8+
9+
Data Fixture Data Provider is any valid PHP callable or valid JSON string that returns an associative array with fixture aliases as key and their respective parameters.
10+
11+
Use Data Fixture Data Provider if the parameters exceeds the maximum characters limit on the line with the directive `with`.
12+
13+
The following example shows the case when the parameters list exceeds the maximum characters limit on the line with the directive `with`.
14+
15+
```php?start_inline=1
16+
class ProductTest extends \PHPUnit\Framework\TestCase
17+
{
18+
/**
19+
* @magentoDataFixture Magento\Catalog\Test\Fixture\Product with:{"price":"12","special_price":10,"tier_prices":[{"customer_group_id":1,"qty":1,"price":9}]}
20+
*/
21+
public function testSpecialPrice(): void
22+
{
23+
}
24+
}
25+
```
26+
27+
## Format
28+
29+
`@magentoDataFixtureDataProvider` takes an argument that points to a callable or contains inline JSON string.
30+
31+
```php?start_inline=1
32+
/**
33+
* @magentoDataFixtureDataProvider <callable>|{}
34+
*/
35+
```
36+
37+
## Principles
38+
39+
1. Callable Data Fixture Data Provider MUST be publicly accessible.
40+
1. Data Fixture Data Provider MUST return an associative array with fixture aliases as key.
41+
1. Data Fixture Data Providers declared at a test method level have a higher priority than Data Fixture Data Providers declared at a test class level.
42+
43+
## Usage
44+
45+
### Inline JSON as Data Provider
46+
47+
Inline JSON data provider is a JSON string with fixture aliases as keys.
48+
49+
The following example shows how to use inline JSON as data provider:
50+
51+
```php?start_inline=1
52+
class ProductsList extends \PHPUnit\Framework\TestCase
53+
{
54+
/**
55+
* @magentoDataFixture Magento\Catalog\Test\Fixture\Product as:product1
56+
* @magentoDataFixture Magento\Catalog\Test\Fixture\Product as:product2
57+
* @magentoDataFixture Magento\Catalog\Test\Fixture\Product as:product3
58+
* @magentoDataFixtureDataProvider {"product1":{"sku":"simple1"}}
59+
* @magentoDataFixtureDataProvider {"product2":{"sku":"simple2"}}
60+
* @magentoDataFixtureDataProvider {"product2":{"sku":"simple3","status":2}}
61+
*/
62+
public function testGetProductsCount(): void
63+
{
64+
}
65+
}
66+
```
67+
68+
### A callable as data provider
69+
70+
A callable data provider is any valid PHP callable that is publicly accessible. The following formats are supported:
71+
72+
- `methodName` a public method declared in the current test class
73+
- `Namespace\Class::method` an external static method
74+
75+
The following example shows how to use test class method as data provider:
76+
77+
```php?start_inline=1
78+
class ProductsList extends \PHPUnit\Framework\TestCase
79+
{
80+
/**
81+
* @magentoDataFixture Magento\Catalog\Test\Fixture\Product as:product1
82+
* @magentoDataFixture Magento\Catalog\Test\Fixture\Product as:product2
83+
* @magentoDataFixture Magento\Catalog\Test\Fixture\Product as:product3
84+
* @magentoDataFixtureDataProvider getProductsCountFixtureDataProvider
85+
*/
86+
public function testGetProductsCount(): void
87+
{
88+
}
89+
90+
public function getProductsCountFixtureDataProvider(): array
91+
{
92+
return [
93+
[
94+
'product1' => [
95+
'sku' => 'simple1'
96+
],
97+
'product2' => [
98+
'sku' => 'simple2'
99+
],
100+
'product3' => [
101+
'sku' => 'simple3',
102+
'status' => Status::STATUS_DISABLED,
103+
],
104+
]
105+
];
106+
}
107+
}
108+
```
109+
110+
### Test case and test method scopes
111+
112+
The `@magentoDataFixtureDataProvider` can be specified for a particular test or for an entire test case.
113+
The basic rules for Data Fixture Data Provider annotation at different levels are:
114+
115+
- `@magentoDataFixtureDataProvider` at a test case level, applies to all fixtures in the test case.
116+
- `@magentoDataFixtureDataProvider` for a particular test, only applies to the fixtures declared at a test method level.
117+
118+
### Restrictions
119+
120+
`@magentoDataFixtureDataProvider` does not recursively merge fixtures data, thus if the fixture alias is defined in multiple `@magentoDataFixtureDataProvider`, only the last value will be used. `@magentoDataFixtureDataProvider` will not apply to a fixture that has an inline data provider with `with` directive.

‎src/guides/v2.4/test/integration/annotations/magento-data-fixture.md

Lines changed: 94 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,24 +4,26 @@ title: Data fixture annotation
44
---
55

66
A data fixture is a PHP script that sets data you want to reuse in your test.
7-
The script can be defined in a separate file or as a local test case method.
7+
The script can be defined in a separate PHP file, class, or as a local test case method.
88

99
Use data fixtures to prepare a database for tests.
1010
The Integration Testing Framework (ITF) reverts the database to its initial state automatically.
1111
To set up a date fixture, use the `@magentoDataFixture` annotation.
1212

1313
## Format
1414

15-
`@magentoDataFixture` takes an argument that points to the data fixture as a filename or local method.
15+
`@magentoDataFixture` takes an argument that points to the data fixture as a filename, full class name, or local method.
1616

1717
```php?start_inline=1
1818
/**
19-
* @magentoDataFixture <script_filename>|<method_name>
19+
* @magentoDataFixture <script_filename>|<method_name>|<fully_qualified_class_name> [as:alias | with:{}]
2020
*/
2121
```
2222

2323
- `<script_filename>` is the filename of the PHP script.
2424
- `<method_name>` is the name of the method declared in the current class.
25+
- `<fully_qualified_class_name>` is the fully qualified name of a class that implements
26+
`Magento\TestFramework\Fixture\DataFixtureInterface` or `Magento\TestFramework\Fixture\RevertibleDataFixtureInterface`.
2527

2628
## Principles
2729

@@ -31,13 +33,16 @@ To set up a date fixture, use the `@magentoDataFixture` annotation.
3133
1. Fixtures declared at a test level have a higher priority than fixtures declared at a test case level.
3234
1. Test case fixtures are applied to each test in the test case, unless a test has its own fixtures declared.
3335
1. Annotation declaration at a test case level does not affect tests that have their own annotation declarations.
36+
1. Fixture alias SHOULD be camelcase.
37+
1. Fixture data provider MUST be a valid JSON string.
3438

3539
## Usage
3640

37-
As mentioned above, there are two ways to declare fixtures:
41+
As mentioned above, there are three ways to declare fixtures:
3842

3943
- as a PHP script file that is used by other tests and test cases.
4044
- as a local method that is used by other tests in the test cases.
45+
- as a [Class][parameterizedDataFixture] that implements `Magento\TestFramework\Fixture\DataFixtureInterface` or `Magento\TestFramework\Fixture\RevertibleDataFixtureInterface`.
4146

4247
### Fixture as a separate file
4348

@@ -82,6 +87,89 @@ Test case that uses the above data fixture: [`dev/tests/integration/testsuite/Ma
8287

8388
[`dev/tests/integration/testsuite/Magento/Cms/Controller/PageTest.php`][] demonstrates an example of the `testCreatePageWithSameModuleName()` test method that uses data from the `cmsPageWithSystemRouteFixture()` data fixture.
8489

90+
### Data Fixture Data Provider
91+
92+
{:.bs-callout-info}
93+
Data Fixture Data Provider is only applicable to Parameterized Data Fixture and is currently only available for Magento Open Source contributors. It will be released for general use with Magento Open Source 2.4.5.
94+
95+
There are two types of data providers:
96+
97+
- Inline JSON as data provider
98+
- [`@magentoDataFixtureDataProvider`][magentoDataFixtureDataProvider] annotation
99+
100+
#### Inline JSON as data provider
101+
102+
Data can be passed to the [Parameterized Data Fixture][parameterizedDataFixture] using the `with` directive as follows:
103+
104+
Example:
105+
106+
```php?start_inline=1
107+
class ProductsList extends \PHPUnit\Framework\TestCase
108+
{
109+
/**
110+
* @magentoDataFixture Magento\Catalog\Test\Fixture\Product with:{"price": 5.0}
111+
* @magentoDataFixture Magento\Catalog\Test\Fixture\Product with:{"price": 10.0}
112+
* @magentoDataFixture Magento\Catalog\Test\Fixture\Product with:{"price": 15.0}
113+
*/
114+
public function testGetProductsCount(): void
115+
{
116+
}
117+
}
118+
```
119+
120+
### Fixture Alias
121+
122+
{:.bs-callout-info}
123+
Fixture Alias is only applicable to Parameterized Data Fixture and is currently only available for Magento Open Source contributors. It will be released for general use with Magento Open Source 2.4.5.
124+
125+
You can give [Parameterized Data Fixture][parameterizedDataFixture] an alias using the `as` directive. The fixture alias is used as a reference to retrieve the data returned by the fixture and also as a reference in other fixtures parameters.
126+
127+
#### Retrieve fixture data in the test
128+
129+
A test can retrieve data that was returned by a [Parameterized Data Fixture][parameterizedDataFixture] using `Magento\TestFramework\Fixture\DataFixtureStorageManager` and the fixture alias.
130+
131+
The following example shows how to retrieve data that was returned by the fixtures:
132+
133+
```php?start_inline=1
134+
class ProductsList extends \PHPUnit\Framework\TestCase
135+
{
136+
/**
137+
* @magentoDataFixture Magento\Catalog\Test\Fixture\Product as:product1
138+
* @magentoDataFixture Magento\Catalog\Test\Fixture\Product as:product2
139+
* @magentoDataFixture Magento\Catalog\Test\Fixture\Product as:product3
140+
*/
141+
public function testGetProductsCount(): void
142+
{
143+
$fixtures = DataFixtureStorageManager::getStorage();
144+
$product1 = $fixtures->get('product1');
145+
$product2 = $fixtures->get('product2');
146+
$product3 = $fixtures->get('product3');
147+
}
148+
}
149+
```
150+
151+
#### Supply data to parameterized data fixture as a variable
152+
153+
It is possible to supply data as a variable from one fixture to another using the fixture alias in one of the following formats:
154+
155+
- `$fixtureAlias$` is a reference to the data that was returned by the fixture with alias `fixtureAlias`.
156+
- `$fixtureAlias.snake_case_property_name$` is a reference to the property `snake_case_property_name` in the data that was returned by the fixture with alias `fixtureAlias`.
157+
158+
The following example shows how a fixture can use the data of another fixture:
159+
160+
```php?start_inline=1
161+
class QuoteTest extends \PHPUnit\Framework\TestCase
162+
{
163+
/**
164+
* @magentoApiDataFixture Magento\Quote\Test\Fixture\GuestCart as:cart
165+
* @magentoApiDataFixture Magento\Quote\Test\Fixture\SetBillingAddress with:{"cart_id":"$cart.id$"}
166+
*/
167+
public function testGetBillingAddress(): void
168+
{
169+
}
170+
}
171+
```
172+
85173
### Test case and test method scopes
86174

87175
The `@magentoDataFixture` can be specified for a particular test or for an entire test case.
@@ -120,6 +208,8 @@ Do not rely on and do not modify an application state from within a fixture, bec
120208
<!-- Link definitions -->
121209

122210
[magentoAppIsolation]: magento-app-isolation.html
211+
[magentoDataFixtureDataProvider]: magento-data-fixture-data-provider.html
212+
[parameterizedDataFixture]: ../parameterized_data_fixture.html
123213
[`dev/tests/integration/testsuite/Magento/Cms/_files/pages.php`]: {{ site.mage2bloburl }}/{{ page.guide_version }}/dev/tests/integration/testsuite/Magento/Cms/_files/pages.php
124214
[`dev/tests/integration/testsuite/Magento/Cms/Block/PageTest.php`]: {{ site.mage2bloburl }}/{{ page.guide_version }}/dev/tests/integration/testsuite/Magento/Cms/Block/PageTest.php
125215
[`dev/tests/integration/testsuite/Magento/Cms/Controller/PageTest.php`]: {{ site.mage2bloburl }}/{{ page.guide_version }}/dev/tests/integration/testsuite/Magento/Cms/Controller/PageTest.php

0 commit comments

Comments
 (0)