Merge branch 'master' into imported-ravi-chandra3197-devdocs-9293

dobooth · web-flow · commit bce6c86dbd22 · 2022-01-04T16:45:54.000-05:00
diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md
@@ -19,7 +19,7 @@ GitHub Issues should only be created for problems/topics related to this project
 Before submitting this issue, please make sure you are complying with our Code of Conduct:
 https://github.com/magento/devdocs/blob/master/.github/CODE_OF_CONDUCT.md
 
-Issues that do not comply with our Code of Conduct or do not contain enough information may be closed at the maintainers' discretion.
+Issues that neither comply with our Code of Conduct or do not contain enough information may be closed at the maintainers' discretion.
 
 Feel free to remove this section before creating this issue.
 -->
diff --git a/.github/ISSUE_TEMPLATE/BUG.md b/.github/ISSUE_TEMPLATE/BUG.md
@@ -1,25 +1,27 @@
 ---
 name: Bug report
 about: Create an issue about a bug on the devdocs website
----
+title: Bug report
+labels: bug
+assignees: dshevtsov
 
-# Bug report
+---
 
 ## Description
 
 <!-- (REQUIRED) What is the issue/current behavior? -->
 
 ### Steps to reproduce
 
-<!-- (OPTIONAL) What needs to be done to replicate this issue? (provide Gist if needed) -->
+<!-- (OPTIONAL) What needs to be done to replicate this issue? You can provide your scenario in a Gist. -->
 
 1. First Step
 1. Second Step
 1. Etc.
 
 ## Expected result
 
-<!-- (REQUIRED) When this issue is resolved, what is the expected result/behavior? -->
+<!-- (REQUIRED) What is the expected result/behavior after resolving this issue? -->
 
 ## Possible solutions
 
@@ -31,7 +33,7 @@ about: Create an issue about a bug on the devdocs website
 
 <!--
 Thank you for taking the time to report this issue!
-GitHub Issues should only be created for problems/topics related to this project's codebase.
+GitHub Issues in this repo should relate to this project's codebase.
 
 Before submitting this issue, please make sure you are complying with our Code of Conduct:
 https://github.com/magento/devdocs/blob/master/.github/CODE_OF_CONDUCT.md
diff --git a/.github/ISSUE_TEMPLATE/COMMUNITY_ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE/COMMUNITY_ISSUE_TEMPLATE.md
diff --git a/.github/ISSUE_TEMPLATE/NEW_FEATURE.md b/.github/ISSUE_TEMPLATE/NEW_FEATURE.md
@@ -1,9 +1,11 @@
 ---
-name: New feature
+name: New devdocs feature
 about: Create a request for new functionality in devdocs
----
+title: Request for a devdocs feature 
+labels: enhancement
+assignees: dshevtsov
 
-# New feature request
+---
 
 ## Description
 
@@ -27,7 +29,7 @@ about: Create a request for new functionality in devdocs
 
 <!--
 Thank you for taking the time to report this issue!
-GitHub Issues should only be created for problems/topics related to this project's codebase.
+GitHub Issues in this repo should only relate to this project's codebase.
 
 Before submitting this issue, please make sure you are complying with our Code of Conduct:
 https://github.com/magento/devdocs/blob/master/.github/CODE_OF_CONDUCT.md
diff --git a/.github/ISSUE_TEMPLATE/NEW_TOPIC.md b/.github/ISSUE_TEMPLATE/NEW_TOPIC.md
@@ -1,9 +1,11 @@
 ---
 name: New topic
 about: Create a request to add missing information to devdocs
----
+title: 'Request for a new topic'
+labels: New Topic
+assignees: ''
 
-# New topic request
+---
 
 ## Description
 
@@ -26,7 +28,7 @@ about: Create a request to add missing information to devdocs
 
 <!--
 Thank you for taking the time to report this issue!
-GitHub Issues should only be created for problems/topics related to this project's codebase.
+GitHub Issues in this repo should relate to this project's codebase.
 
 Before submitting this issue, please make sure you are complying with our Code of Conduct:
 https://github.com/magento/devdocs/blob/master/.github/CODE_OF_CONDUCT.md
diff --git a/.github/ISSUE_TEMPLATE/TOPIC_CLARIFICATION.md b/.github/ISSUE_TEMPLATE/TOPIC_CLARIFICATION.md
@@ -1,9 +1,11 @@
 ---
 name: Topic clarification/correction
 about: Create a request to clarify or correct a documentation topic
----
+title: 'Request for a topic update'
+labels: ''
+assignees: ''
 
-# Topic clarification/correction request
+---
 
 ## Topic Link
 
@@ -23,7 +25,7 @@ about: Create a request to clarify or correct a documentation topic
 
 <!--
 Thank you for taking the time to report this issue!
-GitHub Issues should only be created for problems/topics related to this project's codebase.
+GitHub Issues in this repo should relate to this project's codebase.
 
 Before submitting this issue, please make sure you are complying with our Code of Conduct:
 https://github.com/magento/devdocs/blob/master/.github/CODE_OF_CONDUCT.md
diff --git a/rakelib/test.rake b/rakelib/test.rake
@@ -83,4 +83,26 @@ namespace :test do
     end
     puts "Found #{images.size} dangling images".red
   end
+
+  desc 'Find unused includes'
+  task :unused_includes do
+    puts 'Running a task to find unused _includes'.magenta
+    includes = Dir['src/_includes/**/*']
+    puts "The project contains a total of #{includes.size} includes"
+    puts 'The following includes are not linked:'
+    Dir['src/**/*.{md,html}'].each do |file|
+      # Exclude symmlinks
+      next if File.symlink? file
+
+      includes.delete_if { |include| File.read(file).include?(File.basename(include)) }
+    end
+
+    abort 'No unlinked includes' if includes.empty?
+
+    includes.each do |include|
+      puts "No links for #{include}".yellow
+    end
+    puts "Found #{includes.size} unlinked includes".red
+    puts 'Be careful removing include files. Some include files, such as those in the layout/** directory, may not be linked in the project, but may be used implicitly by the doc theme.'.bold
+  end
 end
diff --git a/src/_data/toc/testing.yml b/src/_data/toc/testing.yml
@@ -34,9 +34,17 @@ pages:
           - label: '@magentoDataFixture'
             url: /test/integration/annotations/magento-data-fixture.html
 
+          - label: '@magentoDataFixtureDataProvider'
+            url: /test/integration/annotations/magento-data-fixture-data-provider.html
+            exclude_versions: ["2.3"]
+
           - label: '@magentoDbIsolation'
             url: /test/integration/annotations/magento-db-isolation.html
 
+        - label: Parameterized Data Fixture
+          url: /test/integration/parameterized_data_fixture.html
+          exclude_versions: ["2.3"]
+
     - label: JavaScript Unit Testing
       children:
 
diff --git a/src/_data/whats-new.yml b/src/_data/whats-new.yml
@@ -4,8 +4,20 @@ description: This page contains recent changes that we think you'd like to know
   We exclude from this list proofreading, spelling checks, and all minor updates.
 link: "/whats-new.html"
 thread: "/whatsnew-feed.xml"
-updated: Mon Dec 20 15:38:51 2021
+updated: Mon Jan 3 15:38:47 2022
 entries:
+- description: Published [release notes](https://devdocs.magento.com/quality-patches/release-notes.html)
+    for the 1.1.8 Quality Patches Tool (QPT) package release.
+  versions: 2.x
+  type: Major Update
+  date: December 20, 2021
+  link: https://github.com/magento-commerce/devdocs/pull/2705
+  merge_commit: 4f69651f1891591171c92aefb0ea3ff527ec1b32
+  contributor: agorbivskyi
+  membership: true
+  labels:
+  - 2.x
+  - Major Update
 - description: Added instructions to manage [_Outgoing emails_  configuration](https://devdocs.magento.com/cloud/project/project-webint-basic.html)
     for Adobe Commerce on cloud Staging and Production environments using the Magento
     Cloud CLI command `magento-cloud environment:info`.
diff --git a/src/guides/v2.4/test/integration/annotations.md b/src/guides/v2.4/test/integration/annotations.md
@@ -16,8 +16,9 @@ Admin Configuration Fixture|`@magentoAdminConfigFixture`|`@magentoAdminConfigFix
 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.
 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.
 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.
-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.
+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.
 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.)
+Data Fixture Data Provider|`@magentoDataFixtureDataProvider`|`@magentoDataFixtureDataProvider <callable>|{}`|Points to a Data Provider callable method or contains an inline JSON string for Parameterized Data Fixtures.
 Application Area|`@magentoAppArea`|`@magentoAppArea adminhtml|frontend|global`|Configures test environment in the context of specified application area.
 Enable/Disable Cache|`@magentoCache`|`@magentoCache <type>|all enabled|disabled`|Enables or disables certain cache segment or all of them to prevent isolation problems.
 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
 1. `@magentoAppIsolation`
 1. `@magentoDbIsolation`
 1. `@magentoDataFixtureBeforeTransaction`
+1. `@magentoDataFixtureDataProvider`
 1. `@magentoDataFixture`
 1. `@magentoIndexerDimensionMode`
 1. `@magentoComponentsDir`
diff --git a/src/guides/v2.4/test/integration/annotations/magento-data-fixture-data-provider.md b/src/guides/v2.4/test/integration/annotations/magento-data-fixture-data-provider.md
@@ -0,0 +1,120 @@
+---
+group: testing
+title: Data fixture data provider annotation
+---
+
+{:.bs-callout-info}
+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.
+
+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.
+
+Use Data Fixture Data Provider if the parameters exceeds the maximum characters limit on the line with the directive `with`.
+
+The following example shows the case when the parameters list exceeds the maximum characters limit on the line with the directive `with`.
+
+```php?start_inline=1
+class ProductTest extends \PHPUnit\Framework\TestCase
+{
+    /**
+     * @magentoDataFixture Magento\Catalog\Test\Fixture\Product with:{"price":"12","special_price":10,"tier_prices":[{"customer_group_id":1,"qty":1,"price":9}]}
+     */
+    public function testSpecialPrice(): void
+    {
+    }
+}
+```
+
+## Format
+
+`@magentoDataFixtureDataProvider` takes an argument that points to a callable or contains inline JSON string.
+
+```php?start_inline=1
+/**
+ * @magentoDataFixtureDataProvider <callable>|{}
+ */
+```
+
+## Principles
+
+1. Callable Data Fixture Data Provider MUST be publicly accessible.
+1. Data Fixture Data Provider MUST return an associative array with fixture aliases as key.
+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.
+
+## Usage
+
+### Inline JSON as Data Provider
+
+Inline JSON data provider is a JSON string with fixture aliases as keys.
+
+The following example shows how to use inline JSON as data provider:
+
+```php?start_inline=1
+class ProductsList extends \PHPUnit\Framework\TestCase
+{
+    /**
+     * @magentoDataFixture Magento\Catalog\Test\Fixture\Product as:product1
+     * @magentoDataFixture Magento\Catalog\Test\Fixture\Product as:product2
+     * @magentoDataFixture Magento\Catalog\Test\Fixture\Product as:product3
+     * @magentoDataFixtureDataProvider {"product1":{"sku":"simple1"}}
+     * @magentoDataFixtureDataProvider {"product2":{"sku":"simple2"}}
+     * @magentoDataFixtureDataProvider {"product2":{"sku":"simple3","status":2}}
+     */
+    public function testGetProductsCount(): void
+    {
+    }
+}
+```
+
+### A callable as data provider
+
+A callable data provider is any valid PHP callable that is publicly accessible. The following formats are supported:
+
+-  `methodName` a public method declared in the current test class
+-  `Namespace\Class::method` an external static method
+
+The following example shows how to use test class method as data provider:
+
+```php?start_inline=1
+class ProductsList extends \PHPUnit\Framework\TestCase
+{
+    /**
+     * @magentoDataFixture Magento\Catalog\Test\Fixture\Product as:product1
+     * @magentoDataFixture Magento\Catalog\Test\Fixture\Product as:product2
+     * @magentoDataFixture Magento\Catalog\Test\Fixture\Product as:product3
+     * @magentoDataFixtureDataProvider getProductsCountFixtureDataProvider
+     */
+    public function testGetProductsCount(): void
+    {
+    }
+
+    public function getProductsCountFixtureDataProvider(): array
+    {
+        return [
+            [
+                'product1' => [
+                    'sku' => 'simple1'
+                ],
+                'product2' => [
+                    'sku' => 'simple2'
+                ],
+                'product3' => [
+                    'sku' => 'simple3',
+                    'status' => Status::STATUS_DISABLED,
+                ],
+            ]
+        ];
+    }
+}
+```
+
+### Test case and test method scopes
+
+The `@magentoDataFixtureDataProvider` can be specified for a particular test or for an entire test case.
+The basic rules for Data Fixture Data Provider annotation at different levels are:
+
+-  `@magentoDataFixtureDataProvider` at a test case level, applies to all fixtures in the test case.
+-  `@magentoDataFixtureDataProvider` for a particular test, only applies to the fixtures declared at a test method level.
+
+### Restrictions
+
+`@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.
diff --git a/src/guides/v2.4/test/integration/annotations/magento-data-fixture.md b/src/guides/v2.4/test/integration/annotations/magento-data-fixture.md
diff --git a/src/guides/v2.4/test/integration/parameterized_data_fixture.md b/src/guides/v2.4/test/integration/parameterized_data_fixture.md
