diff --git a/.gitbook.yaml b/.gitbook.yaml
index 28b445800c..c8f51e1060 100644
--- a/.gitbook.yaml
+++ b/.gitbook.yaml
@@ -109,4 +109,34 @@ redirects:
resources/references/upgrades/core/translation/extension-translation.html: guides/upgrades-migrations/extension-translation.html
resources/references/upgrades/core/translation/language-pack-migration.html: guides/upgrades-migrations/language-pack-migration.html
resources/references/upgrades/administration/: guides/upgrades-migrations/administration/
- resources/references/upgrades/: guides/upgrades-migrations/
\ No newline at end of file
+ resources/references/upgrades/: guides/upgrades-migrations/
+ guides/plugins/plugins/testing/php-unit.html: guides/development/testing/unit/php-unit.html
+ guides/plugins/plugins/testing/jest-storefront.html: guides/development/testing/unit/jest-storefront.html
+ guides/plugins/plugins/testing/jest-admin.html: guides/development/testing/unit/jest-admin.html
+ guides/development/testing/ci.html: guides/development/testing/index.html
+ resources/guidelines/testing/store/: guides/development/testing/testing-guidelines/
+ guides/integrations-api/general-concepts/: guides/development/integrations-api/general-concepts/
+ guides/integrations-api/general-concepts/api-versioning.html: guides/development/integrations-api/general-concepts/api-versioning.html
+ guides/integrations-api/general-concepts/request-headers.html: guides/development/integrations-api/general-concepts/request-headers.html
+ guides/integrations-api/general-concepts/search-criteria.html: guides/development/integrations-api/general-concepts/search-criteria.html
+ guides/integrations-api/general-concepts/partial-data-loading.html: guides/development/integrations-api/general-concepts/partial-data-loading.html
+ guides/integrations-api/general-concepts/generated-reference.html: guides/development/integrations-api/general-concepts/generated-reference.html
+ resources/references/core-reference/dal-reference/filters-reference.html: guides/resources/references/core-reference/dal-reference/filters-reference.html
+ resources/references/core-reference/dal-reference/aggregations-reference.html: guides/resources/references/core-reference/dal-reference/aggregations-reference.html
+ guides/plugins/apps/app-scripts/data-loading.html: guides/integrations-api/general-concepts/search-criteria.html
+ resources/accessibility/accessibility-checklist.html: guides/development/accessibility/accessibility-checklist.html
+ resources/accessibility/storefront-accessibility.html: guides/development/accessibility/storefront-accessibility.html
+ guides/plugins/apps/in-app-purchases.html: guides/development/monetization/in-app-purchases.html
+ guides/plugins/plugins/testing/playwright/actor-pattern.html: guides/development/testing/e2e-playwright/actor-pattern.html
+ guides/plugins/plugins/testing/playwright/best-practices.html: guides/development/testing/e2e-playwright/best-practices.html
+ guides/plugins/plugins/testing/playwright/deployment.html: guides/development/testing/e2e-playwright/deployment.html
+ guides/plugins/plugins/testing/playwright/fixtures.html: guides/development/testing/e2e-playwright/fixtures.html
+ guides/plugins/plugins/testing/playwright/install-configure.html: guides/development/testing/e2e-playwright/install-configure.html
+ guides/plugins/plugins/testing/playwright/language-agnostic-testing.html: guides/development/testing/e2e-playwright/language-agnostic-testing.html
+ guides/plugins/plugins/testing/playwright/local-development.html: guides/development/testing/e2e-playwright/local-development.html
+ guides/plugins/plugins/testing/playwright/page-object.html: guides/development/testing/e2e-playwright/page-object.html
+ guides/plugins/plugins/testing/playwright/test-data-service.html: guides/development/testing/e2e-playwright/test-data-service.html
+ guides/plugins/plugins/testing/playwright/test-suite-types.html: guides/development/testing/e2e-playwright/test-suite-types.html
+ guides/plugins/plugins/testing/playwright/test.html: guides/development/testing/e2e-playwright/test.html
+ guides/plugins/plugins/testing/cypress/cypress-best-practises.html: guides/development/testing/legacy/cypress/cypress-best-practises.html
+ guides/plugins/plugins/testing/cypress/cypress-end-to-end-testing/: guides/development/testing/legacy/cypress/
\ No newline at end of file
diff --git a/.wordlist.txt b/.wordlist.txt
index e90ee14f11..63d7e2cc6c 100644
--- a/.wordlist.txt
+++ b/.wordlist.txt
@@ -631,6 +631,7 @@ ORMs
OSS
OTEL
OTLP
+OWASP
ObjectField
ObjectType
OffCanvas
@@ -1768,6 +1769,7 @@ resolver's
resolvers
resubmittable
rethrown
+retryability
returnUrl
revalidation
rfc
diff --git a/concepts/framework/in-app-purchases.md b/concepts/framework/in-app-purchases.md
index 2d1d83afb3..fd7230d092 100644
--- a/concepts/framework/in-app-purchases.md
+++ b/concepts/framework/in-app-purchases.md
@@ -5,13 +5,13 @@ nav:
---
-# In-App purchases (IAP)
+# In-App Purchases (IAP)
::: info
In-App Purchase is available since Shopware version 6.6.9.0
:::
-In-App Purchases are a way to lock certain features behind a paywall within the same extension.
+In-App Purchases allow you to lock certain features behind a paywall within the same extension.
This is useful for developers who want to offer a free version of their extension with limited features and a paid version with more features.
## Creation
@@ -25,7 +25,7 @@ This JWT ensures that purchase data cannot be tampered with or spoofed and allow
All bought In-App Purchases are part of the JWT claims.
To verify the JWT signature, you can use the JSON Web Key Set (JWKS) available at [`https://api.shopware.com/inappfeatures/jwks`](https://api.shopware.com/inappfeatures/jwks)
-Shopware automatically verifies the signature for the use within the Core and Admin.
+Shopware automatically verifies the signature for use within the Core and Admin.
Tokens are retrieved when a new purchase is made and during periodic updates.
You can also manually trigger an update by running the command `bin/console scheduled-task:run-single in-app-purchase.update` or by calling the `/api/_action/in-app-purchases/refresh` endpoint.
@@ -37,12 +37,12 @@ In-app purchases are optimized for use with app servers.
Whenever Shopware sends a request to the app server, it includes the [IAP JWT](#token).
The app server can use this token to validate active purchases and unlock related features accordingly.
-Plugins are inherently less secure, as their open nature makes them more vulnerable to spoofing or tampering.
+Plugins are inherently less secure because their open nature makes them more vulnerable to spoofing and tampering.
-`, ``, ``, ``.
- Always pair `` elements with form controls using `for` and `id`. Avoid relying solely on `placeholder` text for labeling.
-### Set the Correct Document Language
+### Set the correct document language
Proper language settings help screen readers use accurate pronunciation and intonation:
- Add `lang="en"` (or the appropriate language code) to the `` tag.
-### Ensure Accessible Forms
+### Ensure accessible forms
-All form fields must be clearly labeled and error states must be identifiable:
+All form fields must be clearly labeled, and error states must be identifiable:
- Use ``, `aria-label`, or `aria-labelledby`.
- Provide error messages that are clear and easy to locate.
-- Don’t rely solely on color (e.g., red) to indicate errors. You can use icons or text additionally.
+- Don’t rely solely on color (e.g., red) to indicate errors. You can also use icons or text.
- Use `aria-describedby` to connect input fields to help or error messages.
-### Manage Focus
+### Manage focus
Ensure users know where they are and can move through the interface logically:
-- Use `tabindex="0"` for custom interactive elements. Try to not mess around with the tabindex if possible and keep the "natural" tab flow.
-- Do not remove focus outlines unless replaced with a clear visible alternative.
-- Use `focus()` to direct user attention (e.g. after form errors or modal open).
-- Each interactive element that can be clicked or navigated by keyboard (``, `` etc.) must have a clearly visible focus indication.
+- Use `tabindex="0"` for custom interactive elements. Try not to mess around with the tabindex if possible, and keep the "natural" tab flow.
+- Do not remove focus outlines unless replaced with a clear, visible alternative.
+- Use `focus()` to direct user attention (e.g., after form errors or modal open).
+- Each interactive element that can be clicked or navigated by keyboard (``, ``, etc.) must have a clearly visible focus indication.
-### Keyboard Accessibility
+### Keyboard accessibility
Users should be able to navigate and interact with all features using only the keyboard:
@@ -52,7 +52,7 @@ Users should be able to navigate and interact with all features using only the k
- Avoid using `onclick` on non-focusable elements without keyboard support.
- Custom widgets must respond to arrow keys and expected keyboard patterns.
-### Use ARIA Carefully
+### Use ARIA carefully
Use ARIA roles and attributes only when native HTML doesn’t work.
@@ -60,51 +60,51 @@ Use ARIA roles and attributes only when native HTML doesn’t work.
- Apply `aria-expanded`, `aria-controls`, and `aria-hidden` for toggleable UI elements.
- Prefer native HTML elements over ARIA whenever possible to reduce complexity.
-### Provide Live Region Updates
+### Provide live region updates
Ensure real-time changes are accessible:
-- Use `aria-live="polite"` or `aria-live="assertive"` for real-time updates (e.g. validation messages, chat widgets).
+- Use `aria-live="polite"` or `aria-live="assertive"` for real-time updates (e.g., validation messages, chat widgets).
-### Manage Page Titles and Headings
+### Manage page titles and headings
Headings and titles provide structure and orientation. It helps users understand page structure:
-- Always update the `` tag on page load or route change.
+- Always update the `<title>` tag on page load or route change.
- Use one `<h1>` per page, followed by correct heading hierarchy (`<h2>`, `<h3>`, etc.).
-### Support Skip Links
+### Support skip links
Help keyboard users skip repetitive content:
- Include a skip link at the top of the page:
- ```html
+ ```html
<a href="#main-content" class="skip-link">Skip to main content</a>
- ```
+ ```
-### Control Focus When Using Modals or Popovers
+### Control focus when using modals or popovers
Focus should remain within the modal and return to the trigger element after closing:
- Trap focus while the modal is open.
- Return focus to the initiating element once it is closed.
-### Avoid Auto-Playing Audio or Video
+### Avoid auto-playing audio or video
If unavoidable, make sure users can easily pause or stop it:
- Provide controls on `<video>` or `<audio>` elements.
- Avoid autoplay unless muted and non-disruptive.
-### Ensure Unique IDs and ARIA Attributes
+### Ensure unique IDs and ARIA attributes
Avoid duplicated IDs to maintain screen reader reliability:
- Validate that `id` attributes are unique.
- Ensure any referenced IDs in `aria-labelledby` or `aria-describedby` exist and are not duplicated.
-### Test with Assistive Technologies
+### Test with assistive technologies
Test your site with real-world tools and scenarios:
@@ -116,4 +116,4 @@ Test your site with real-world tools and scenarios:
Following this checklist will help ensure your storefront is usable by everyone, regardless of ability. It also improves SEO, performance, and user satisfaction for all visitors.
-Regularly audit your code, test with assistive technologies, and stay updated with evolving accessibility standards. Inclusive design is good design.
+Regularly audit your code, test with assistive technologies, and stay up to date with evolving accessibility standards. Inclusive design is good design.
diff --git a/guides/development/accessibility/index.md b/guides/development/accessibility/index.md
new file mode 100644
index 0000000000..945e99ccee
--- /dev/null
+++ b/guides/development/accessibility/index.md
@@ -0,0 +1,23 @@
+---
+nav:
+ title: Accessibility
+ position: 10
+---
+
+# Accessibility
+
+Shopware is committed to creating inclusive and barrier-free shopping experiences. Accessibility affects both the core Storefront and all custom themes and extensions. Developers are responsible for ensuring their implementations comply with accessibility standards, such as WCAG 2.1 Level AA.
+
+## In this section
+
+<PageRef page="./storefront-accessibility" />
+<PageRef page="./accessibility-checklist" />
+
+## Why accessibility matters
+
+* Legal compliance (e.g., EU accessibility regulations)
+* Better usability for all users
+* Improved SEO and performance
+* Future-proof storefront implementations
+
+Shopware continuously introduces accessibility improvements in new releases. Always test extensions with the `ACCESSIBILITY_TWEAKS` feature flag enabled to ensure compatibility.
diff --git a/resources/accessibility/storefront-accessibility.md b/guides/development/accessibility/storefront-accessibility.md
similarity index 81%
rename from resources/accessibility/storefront-accessibility.md
rename to guides/development/accessibility/storefront-accessibility.md
index 4da5be3c68..7d04ee4c17 100644
--- a/resources/accessibility/storefront-accessibility.md
+++ b/guides/development/accessibility/storefront-accessibility.md
@@ -8,22 +8,22 @@ nav:
At Shopware, we are committed to creating inclusive and barrier-free shopping experiences for our merchants and their customers.
-## What shopware does to ensure accessibility?
+## What does Shopware do to ensure accessibility?
-* Shopware is committed to fulfill the [WCAG 2.1 AA](https://www.w3.org/TR/WCAG21/) accessibility guidelines and Barrier-Free Information Technology Regulation (BITV 2.0) in the Storefront.
+* Shopware is committed to fulfilling the [WCAG 2.1 AA](https://www.w3.org/TR/WCAG21/) accessibility guidelines and Barrier-Free Information Technology Regulation (BITV 2.0) in the Storefront.
* You can find more information on [shopware.design](https://shopware.design/foundations/accessibility.html) and [in our blog post](https://www.shopware.com/en/news/accessible-online-store-by-2025/).
* The Storefront is using [Bootstrap components](https://getbootstrap.com/docs/5.3/getting-started/accessibility/) that already consider good accessibility practices, for example, using aria roles.
-* Much of the HTML structure and CSS styling already fulfill accessibility guidelines. However, there are still [open accessibility issues](#Overview-of-known-accessibility-issues) that will be addressed.
+* Much of the HTML structure and CSS styling already fulfill accessibility guidelines. However, there are still [open accessibility issues](https://github.com/shopware/shopware/issues?q=state%3Aopen%20label%3Aarea%2Faccessibility) that will be addressed.
* Automated [E2E testing with playwright](https://github.com/shopware/shopware/tree/trunk/tests/acceptance) and axe reporter are used to ensure future accessibility.
## How are core accessibility improvements released?
-Starting from **Shopware 6.6+,** accessibility improvements have been introduced, and **6.7+** includes further enhancements. Accessibility improvements are rolled out in regular minor releases, similar to other improvements or bug-fixes.
-There is no large "accessibility release" planned that ships all accessibility improvements at once.
+Starting with **Shopware 6.6+**, accessibility improvements have been introduced, and **6.7+** includes further enhancements. Accessibility improvements are rolled out in regular minor releases, similar to other improvements or bug fixes.
+There is no significant "accessibility release" planned that ships all accessibility improvements at once.
## How to deal with breaking accessibility changes?
-Ensuring an accessible shop page can require changes in the HTML/Twig structure or the CSS. This can cause unintended behavior for an extension that is modifying an area that is being changed to improve accessibility.
+Ensuring an accessible shop page can require changes in the HTML/Twig structure or the CSS. This can cause unintended behavior in an extension that modifies an area being changed to improve accessibility.
Because of this, breaking accessibility changes are not enabled by default. All accessibility changes that include breaking changes are implemented behind a feature flag:
@@ -31,52 +31,52 @@ Because of this, breaking accessibility changes are not enabled by default. All
ACCESSIBILITY_TWEAKS=1
```
-However, breaking accessibility changes are still released regularly inside minor releases. They are just not active by default to not cause a breaking change.
+However, breaking accessibility changes are still released regularly inside minor releases. They are not active by default to not cause a breaking change.
-The feature flag `ACCESSIBILITY_TWEAKS` can be activated inside your `.env`, similar to the major feature flags like `V6_7_0_0`. When the feature flag is enabled, all available accessibility improvements are activated.
-This allows you to check if your project or extension is effected by the change and already prepare an adaptation to the change if it is necessary.
+The feature flag `ACCESSIBILITY_TWEAKS` can be activated in your `.env`, similar to the major feature flags like `V6_7_0_0`. When the feature flag is enabled, all available accessibility improvements are activated.
+This allows you to check whether your project or extension is affected by the change and to prepare an adaptation already if necessary.
::: warning
-With the major version v6.7.0 all accessibility improvements will become the default.
+With the major version v6.7.0, all accessibility improvements will become the default.
:::
### Example of a breaking accessibility change
-Let's say, for example, that a list is not using a proper markup, and it is changed to improve accessibility.
+Let's say, for example, that a list is not using proper markup and is changed to improve accessibility.
This is what a suboptimal HTML structure could look like:
```twig
<div class="sidebar-list">
- {% block component_list_items %}
- <div class="list-item"><a href="#">Item</a></div>
- <div class="list-item"><a href="#">Item</a></div>
- <div class="list-item"><a href="#">Item</a></div>
- {% endblock %}
+ {% block component_list_items %}
+ <div class="list-item"><a href="#">Item</a></div>
+ <div class="list-item"><a href="#">Item</a></div>
+ <div class="list-item"><a href="#">Item</a></div>
+ {% endblock %}
</div>
```
-Let's assume it should be changed to a proper list. Instead of implementing this right away, it is implemented behind the `ACCESSIBILITY_TWEAKS` flag, including instructions how it should be changed:
+Let's assume it should be changed to a proper list. Instead of implementing this right away, it is implemented behind the `ACCESSIBILITY_TWEAKS` flag, including instructions on how it should be changed:
```twig
{# @deprecated tag:v6.7.0 - The list will be changed to `<ul>` and `<li>` to improve accessibility #}
{% if feature('ACCESSIBILITY_TWEAKS') %}
- <ul class="sidebar-list">
- {% block component_list_items_inner %}
- <li class="list-item"><a href="#">Item</a></li>
- <li class="list-item"><a href="#">Item</a></li>
- <li class="list-item"><a href="#">Item</a></li>
- {% endblock %}
- </ul>
+ <ul class="sidebar-list">
+ {% block component_list_items_inner %}
+ <li class="list-item"><a href="#">Item</a></li>
+ <li class="list-item"><a href="#">Item</a></li>
+ <li class="list-item"><a href="#">Item</a></li>
+ {% endblock %}
+ </ul>
{% else %}
- <div class="sidebar-list">
- {# @deprecated tag:v6.7.0 - Use `component_list_items_inner` instead with `<li>` #}
- {% block component_list_items %}
- <div class="list-item"><a href="#">Item</a></div>
- <div class="list-item"><a href="#">Item</a></div>
- <div class="list-item"><a href="#">Item</a></div>
- {% endblock %}
- </div>
+ <div class="sidebar-list">
+ {# @deprecated tag:v6.7.0 - Use `component_list_items_inner` instead with `<li>` #}
+ {% block component_list_items %}
+ <div class="list-item"><a href="#">Item</a></div>
+ <div class="list-item"><a href="#">Item</a></div>
+ <div class="list-item"><a href="#">Item</a></div>
+ {% endblock %}
+ </div>
{% endif %}
```
@@ -87,27 +87,27 @@ If the block `component_list_items` is being extended, the new accessibility cha
{# Consider the new structure already #}
{% block component_list_items_inner %}
- {{ parent() }}
- <li class="list-item"><a href="#">My item</a></li>
+ {{ parent() }}
+ <li class="list-item"><a href="#">My item</a></li>
{% endblock %}
{# This can be removed after v6.7.0 #}
{% block component_list_items %}
- {{ parent() }}
- <div class="list-item"><a href="#">My item</a></div>
+ {{ parent() }}
+ <div class="list-item"><a href="#">My item</a></div>
{% endblock %}
```
## Overview of accessibility issues for iteration 1
::: info
-With accessibility iteration 1 we have addressed the most critical accessibility problems and implemented multiple improvements.
+With accessibility iteration 1, we have addressed the most critical accessibility problems and implemented multiple improvements.
:::
### Continuous efforts to ensure accessibility
-We are continuously testing our core Storefront to meet accessibility requirements. This includes screen reader usage, keyboard-operation or color contrast analyzes.
-We are using the [WCAG 2.1 Level AA](https://www.w3.org/TR/WCAG21/) standard and do our best to solve all issues to meet the WCAG 2.1 requirements.
+We are continuously testing our core Storefront to meet accessibility requirements. This includes screen reader usage, keyboard operation, or color contrast analysis.
+We are using the [WCAG 2.1 Level AA](https://www.w3.org/TR/WCAG21/) standard and do our best to resolve all issues to meet its requirements.
### Overview of released accessibility improvements
@@ -141,14 +141,14 @@ We are using the [WCAG 2.1 Level AA](https://www.w3.org/TR/WCAG21/) standard and
| No keyboard traps should occur in the Storefront | - | Verification work without released code changes | - |
| Mechanism for the user to pause, stop, or hide moving content | - | Verification work without released code changes | - |
| Add text to components that only work with icons to identify their purpose | - | - |
-| Check if all non-text content has text alternative and provide if necessary | - | - |
+| Check if all non-text content has a text alternative and provide if necessary | - | - |
| Provide error correction suggestions | - | - |
-| Text styles needs to be adjusted (line height, paragraph spacing) | - | - |
+| Text styles need to be adjusted (line height, paragraph spacing) | - | - |
| Keyboard/Tabs should work for nav main-navigation-menu | - | - |
### Overview of known accessibility issues
-To report any new accessibility issues, click the New Issue button, select Bug Report, fill out the require fields and make sure to add the area/accessibility label.
+To report any new accessibility issues, click the New Issue button, select Bug Report, fill out the required fields, and make sure to add the area/accessibility label.
Here is a reference to the existing [accessibility Issues](https://github.com/shopware/shopware/issues?q=state%3Aopen%20label%3Aarea%2Faccessibility).
## Best practices for accessibility (a11y) in Shopware extensions
@@ -159,13 +159,13 @@ Ensuring accessibility in your Shopware extension improves **usability, inclusiv
#### Activate the accessibility feature flag
-Enable the **feature flag** to test changes before release by activating the feature flag in your local environment, modify your `project-root/.env`.
+Enable the **feature flag** to test changes before release by activating it in your local environment. Modify your `project-root/.env`.
```env
ACCESSIBILITY_TWEAKS=1
```
-Once enabled, the `ACCESSIBILITY_TWEAKS` feature flag, a re-compilation of the theme is needed to enable all styling improvements like adjusted font-sizes.
+Once `ACCESSIBILITY_TWEAKS` is enabled, a theme recompilation is needed to apply all styling improvements, such as adjusted font sizes.
```text
bin/console theme:compile
@@ -191,9 +191,9 @@ Use automated tools to **detect common accessibility issues** in your extension:
While automation helps, **manual checks** ensure real-world usability:
-✔ **Keyboard Navigation** – Ensure users can navigate your store using `Tab`, `Enter`, and `Esc`.
-✔ **Screen Readers** – Test with **NVDA (Windows)** or **VoiceOver (Mac/iOS)**.
-✔ **Color Contrast Checks** – Use [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/) to verify readability.
+* **Keyboard Navigation** – Ensure users can navigate your store using `Tab`, `Enter`, and `Esc`.
+* **Screen Readers** – Test with **NVDA (Windows)** or **VoiceOver (Mac/iOS)**.
+* **Color Contrast Checks** – Use [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/) to verify readability.
### 3. Validating accessibility in extensions
@@ -215,7 +215,7 @@ While automation helps, **manual checks** ensure real-world usability:
|---------------------|------------------------|
| **6.7+** | Full A11y improvements available for testing |
| **6.6+** | Accessibility features introduced (use `ACCESSIBILITY_TWEAKS` feature flag) |
-| **Shopware 5** | 🚫 **No accessibility support** |
+| **Shopware 5** | **No accessibility support** |
### 5. Getting help with accessibility
@@ -225,4 +225,4 @@ While automation helps, **manual checks** ensure real-world usability:
## Conclusion
-Understanding accessibility best-practices is just the beginning. To truly create an inclusive storefront, these ideas must be translated into practice. To help you turn these into action, we have created a comprehensive [Storefront Accessibility Checklist](./accessibility-checklist.md). It outlines the key technical and design practices needed to build accessible interfaces—from semantic HTML to keyboard navigation and ARIA usage.
+Understanding accessibility best practices is just the beginning. To truly create an inclusive storefront, these ideas must be translated into practice. To help you turn these into action, we have created a comprehensive [Storefront Accessibility Checklist](./accessibility-checklist.md). It outlines the key technical and design practices needed to build accessible interfaces—from semantic HTML to keyboard navigation and ARIA usage.
diff --git a/guides/development/index.md b/guides/development/index.md
new file mode 100644
index 0000000000..42a93d806f
--- /dev/null
+++ b/guides/development/index.md
@@ -0,0 +1,95 @@
+---
+nav:
+ title: Development
+ position: 1
+
+---
+
+# Development
+
+This guide covers post-installation information for building, extending, and debugging Shopware during development. The development path depends on what is being built:
+
+* Custom project
+* Extension: apps, plugins, or plugin-based themes
+* Storefront customization
+* Administration extension
+* Headless integration
+
+All development scenarios share common foundations:
+
+* APIs
+* Testing
+* Tooling
+* CLI and system commands
+* Configuration
+* Debugging
+
+To build a custom Shopware project without creating an extension for distribution, start here.
+
+## Extension development
+
+To build an extension, first choose the correct type:
+
+* Plugin
+* App
+* Plugin-based theme
+
+Each extension guide walks you through the full development flow: creation → lifecycle → implementation → testing.
+
+To sell an extension or offer paid features, see the [Monetization guide](./monetization) for available models such as paid extensions, In-App Purchases, and commission-based integrations.
+
+## Typical development workflow
+
+Most development follows this sequence:
+
+* Set up the environment
+* Create the project or extension
+* Install and activate it
+* Implement business logic
+* Extend Storefront or Administration
+* Add configuration or database changes (if required)
+* Test and debug
+
+Before beginning implementation, review the recommended [Code structure](extensions/code-structure.md). A consistent architecture prevents long-term maintenance issues and reduces upgrade friction.
+
+:::tip Upgrade awareness
+Before starting new development, review the [Upgrades and Migrations](../upgrades-and-migrations/index.md) section to avoid patterns that are deprecated or scheduled for removal.
+:::
+
+:::info Upgrade impact in real projects
+Upgrade complexity depends on the installation:
+
+* Heavy custom code increases migration effort.
+* No custom code but 60 Store plugins can be equally complex.
+* Most real-world projects fall somewhere in between.
+
+A consistent architecture, centralized CI, and controlled extension strategy help you get ahead of upgrade pain.
+:::
+
+Set up automated testing and [Continuous Integration (CI)](testing/ci.md) early. Static analysis, tests, and reproducible builds help catch breaking changes before they reach production.
+
+## Working in the system
+
+### Administration
+
+To begin any development, first access the Administration by opening [http://localhost/admin](http://localhost/admin).
+
+Use the Administration to:
+
+* Install and activate extensions
+* Configure the system
+* Manage entities such as products and customers
+* Verify extension behavior
+
+The Administration is part of the runtime environment and will be used throughout development.
+
+### Development tooling
+
+* `bin/console`: Shopware's built-in CLI, used for installing and activating plugins, running database migrations, clearing caches, executing scheduled tasks, and inspecting system state. See [command reference guide](resources/references/core-reference/commands-reference.html).
+* The standalone [Shopware CLI](https://developer.shopware.com/docs/products/cli/installation.html) supports project scaffolding, CI/CD workflows, automation tasks, and more. See the [helper commands guide](products/cli/project-commands/helper-commands.html).
+* IDE support: Shopware provides a [PHPStorm plugin](shopware-toolbox.md) and [VS Code extension](../development/tooling/vscode.md).
+*[Deployment Helper](guides/hosting/deployment-helper/): Supports database and maintenance operations for deployments (e.g., migrations, cache handling).
+
+### Troubleshooting
+
+The [troubleshooting](/troubleshooting) guides provide reference information about the data abstraction layer (DAL), flow, and rules.
diff --git a/guides/integrations-api/general-concepts/generated-reference.md b/guides/development/integrations-api/general-concepts/generated-reference.md
similarity index 77%
rename from guides/integrations-api/general-concepts/generated-reference.md
rename to guides/development/integrations-api/general-concepts/generated-reference.md
index aa7f387b95..2e6957b589 100644
--- a/guides/integrations-api/general-concepts/generated-reference.md
+++ b/guides/development/integrations-api/general-concepts/generated-reference.md
@@ -9,22 +9,22 @@ nav:
Shopware generates schemas for both HTTP APIs that can be interpreted by API client libraries and documentation tools, such as [Stoplight.io](https://stoplight.io/).
-These schemas are generated using PHP annotations based on the [swagger-php](https://github.com/zircote/swagger-php) library. When building API extensions, you can also leverage these annotations to let Shopware generate standardized endpoint documentation for your custom endpoints on-the-fly.
+These schemas are generated using PHP annotations based on the [swagger-php](https://github.com/zircote/swagger-php) library. When building API extensions, you can also leverage these annotations to let Shopware generate standardized endpoint documentation for your custom endpoints on the fly.
::: warning
-Due to security restrictions, your **`APP_ENV`** environment variable has to be set to **`dev`** to access any of the specifications described below.
+Due to security restrictions, your **`APP_ENV`** environment variable must be set to **`dev`** to access the specifications described below.
:::
## Stoplight
-The easiest way to access the generated schema is Stoplight. [Stoplight](https://docs.stoplight.io/) is a collaborative platform equipping your team with tooling across the API lifecycle that helps them build quality APIs efficiently. Shopware already ships with these user interfaces. They are accessible at the following endpoint relative to their respective base path:
+The easiest way to access the generated schema is Stoplight. [Stoplight](https://docs.stoplight.io/) is a collaborative platform that equips your team with tooling across the API lifecycle to help them build high-quality APIs efficiently. Shopware already ships with these user interfaces. They are accessible at the following endpoint relative to their respective base path:
```text
/(api|store-api)/_info/stoplightio.html
```
::: info
-The above path is relative and contains `api` (Admin API) and `store-api` seperated by a pipe. Please choose the appropriate option.
+The above path is relative and contains `api` (Admin API) and `store-api` separated by a pipe. Please choose the appropriate option.
:::
You will find a list of all generic endpoints (entity endpoints like product, category, etc.) for the **Admin API** here `api/_info/stoplightio.html?type=jsonapi#/` or access it via the top navigation bar.
diff --git a/guides/development/integrations-api/general-concepts/index.md b/guides/development/integrations-api/general-concepts/index.md
new file mode 100644
index 0000000000..dae14922c0
--- /dev/null
+++ b/guides/development/integrations-api/general-concepts/index.md
@@ -0,0 +1,28 @@
+---
+nav:
+ title: General Concepts
+ position: 10
+
+---
+
+# General Concepts
+
+Even though the Admin API and the Store API serve very different purposes, they share some commonalities worth noting.
+
+## Querying data
+
+For the Admin API, these apply to the `/search` endpoint, whilst for the Store API, they apply to almost every endpoint that returns a list of records.
+
+It starts with a simple underlying concept that encapsulates your entire search description in a single generic object, called the **search criteria**.
+
+<PageRef page="search-criteria" />
+
+Additional instructions can be specified using **request headers**.
+
+<PageRef page="request-headers" />
+
+## Documentation
+
+Here you find a common approach regarding the way that Shopware provides endpoint references for its APIs:
+
+<PageRef page="generated-reference" />
diff --git a/guides/integrations-api/general-concepts/partial-data-loading.md b/guides/development/integrations-api/general-concepts/partial-data-loading.md
similarity index 52%
rename from guides/integrations-api/general-concepts/partial-data-loading.md
rename to guides/development/integrations-api/general-concepts/partial-data-loading.md
index aa790b49ce..25d2bbb34f 100644
--- a/guides/integrations-api/general-concepts/partial-data-loading.md
+++ b/guides/development/integrations-api/general-concepts/partial-data-loading.md
@@ -7,11 +7,11 @@ nav:
# Partial Data Loading
-`Partial data loading` allows you to select specific fields of an entity to be returned by the API. This can be useful if you only need a few fields of an entity and don't want to load the whole entity. This can reduce the response size and improve the performance of your application.
+`Partial data loading` allows you to select specific fields of an entity to be returned by the API. This can be useful if you only need a few fields of an entity and don't want to load the whole entity. This can reduce response size and improve your application's performance.
## Partial data loading vs Includes
-`Partial data loading` is different from the [includes](./search-criteria.md#includes-apialias) feature. The `includes` works as post-output processing, so the complete entity or data is loaded in the backend side and then filtered, while `partial data loading` works already on database level. This means that the database only loads the requested fields and not the whole entity.
+`Partial data loading` is different from the [includes](./search-criteria.md#includes-apialias) feature. The `includes` works as post-output processing, so the complete entity or data is loaded on the backend and then filtered, while `partial data loading` works already at the database level. This means the database only loads the requested fields, not the entire entity.
### Usage
@@ -22,9 +22,9 @@ Content-Type: application/json
Accept: application/json
{
- "fields": [
- "name"
- ]
+ "fields": [
+ "name"
+ ]
}
```
@@ -33,23 +33,23 @@ Accept: application/json
{
"total": 1,
"data": [
- {
+ {
"extensions": [],
"_uniqueIdentifier": "018cda3ac909712496bccc065acf0ff4",
"translated": {
"name": "US-Dollar"
- },
+ },
"id": "018cda3ac909712496bccc065acf0ff4",
"name": "US-Dollar",
"isSystemDefault": false,
"apiAlias": "currency"
- }
- ],
+ }
+ ],
"aggregations": []
}
```
-Fields can also reference fields of associations like in this example the assigned salesChannel names of the currency. The API adds the necessary associations automatically.
+Fields can also reference fields of associations, like in this example, the assigned salesChannel names of the currency. The API automatically adds the necessary associations.
```http
POST /api/search/currency
@@ -58,10 +58,10 @@ Content-Type: application/json
Accept: application/json
{
- "fields": [
- "name",
- "salesChannels.name"
- ]
+ "fields": [
+ "name",
+ "salesChannels.name"
+ ]
}
```
@@ -70,57 +70,57 @@ Accept: application/json
{
"total": 1,
"data": [
- {
+ {
"extensions": [],
"_uniqueIdentifier": "018cda3ac909712496bccc065acf0ff4",
"translated": {
"name": "US-Dollar"
- },
+ },
"id": "018cda3ac909712496bccc065acf0ff4",
"name": "US-Dollar",
"salesChannels": [
- {
+ {
"extensions": [],
"_uniqueIdentifier": "018cda3af56670d6a3fa515a85967bd2",
"translated": {
"name": "Storefront"
- },
+ },
"id": "018cda3af56670d6a3fa515a85967bd2",
"name": "Storefront",
"apiAlias": "sales_channel"
- }
- ],
+ }
+ ],
"isSystemDefault": false,
"apiAlias": "currency"
- }
- ],
+ }
+ ],
"aggregations": []
}
```
## Default fields
-Some fields are always loaded like the `id` or join relevant fields like foreign keys, these are necessary for the API to work correctly and can't be removed.
+Some fields are always loaded, such as `id` and join-related fields like foreign keys; these are necessary for the API to work correctly and can't be removed.
## Runtime fields
-Some fields in the API are generated at runtime like `isSystemDefault` of the currency. These fields are loaded by default when the referenced data is available, otherwise they can be requested in the `fields` parameter to force the API to load them.
+Some fields in the API are generated at runtime, such as `isSystemDefault` for the currency. These fields are loaded by default when the referenced data is available; otherwise, they can be requested in the `fields` parameter to force the API to load them.
-For custom entity definitions with runtime flag, the referenced fields need to be specified inside the constructor. See an example from the core:
+For custom entity definitions with a runtime flag, the referenced fields must be specified in the constructor. See an example from the core:
```php
protected function defineFields(): FieldCollection
{
return new FieldCollection([
- (new IdField('id', 'id'))->addFlags(new ApiAware(), new PrimaryKey(), new Required()),
- (new StringField('path', 'path'))->addFlags(new ApiAware()),
+ (new IdField('id', 'id'))->addFlags(new ApiAware(), new PrimaryKey(), new Required()),
+ (new StringField('path', 'path'))->addFlags(new ApiAware()),
- // When this field is requested, we need the data of path field to generate the url
- (new StringField('url', 'url'))->addFlags(new ApiAware(), new Runtime(['path'])),
- ]);
+ // When this field is requested, we need the data of the path field to generate the URL
+ (new StringField('url', 'url'))->addFlags(new ApiAware(), new Runtime(['path'])),
+ ]);
}
```
## Limitations
-The current limitation of the `partial data loading` is that it only works on the Entity level. Any custom responses like a product detail page or CMS in the Store API can't be used with this feature, as the Store API needs the whole entity to generate the response. If you need a small response, we recommend using the [includes](./search-criteria.md#includes-apialias) feature of the Search API.
+The current limitation of the `partial data loading` is that it only works on the Entity level. Any custom responses, such as a product detail page or CMS, in the Store API can't be used with this feature, as the Store API needs the entire entity to generate the response. If you need a small response, we recommend using the [includes](./search-criteria.md#includes-apialias) feature of the Search API.
diff --git a/guides/integrations-api/general-concepts/request-headers.md b/guides/development/integrations-api/general-concepts/request-headers.md
similarity index 65%
rename from guides/integrations-api/general-concepts/request-headers.md
rename to guides/development/integrations-api/general-concepts/request-headers.md
index b570683895..06401d3ebb 100644
--- a/guides/integrations-api/general-concepts/request-headers.md
+++ b/guides/development/integrations-api/general-concepts/request-headers.md
@@ -9,7 +9,7 @@ nav:
## sw-language-id
-By default, the API delivers the entities via the system language. This can be changed by specifying a language id using the `sw-language-id` header.
+By default, the API returns entities in the system language. This can be changed by specifying a language ID using the `sw-language-id` header.
```bash
POST /api/search/product
@@ -17,14 +17,14 @@ POST /api/search/product
```
::: info
-Shopware only populates a translatable field if there is an explicit translation for that field. Instead, the `translated` object always contains values, if necessary fallbacks.
+Shopware only populates a translatable field if there is an explicit translation for that field. Instead, the `translated` object always contains values, with fallbacks if necessary.
-**Example:** You instruct Shopware to fetch the french translation of a product using the `sw-language-id` header, but there's no french translation for the products name. The resulting field `product.name` will be `null`. When you're building applications, always use `product.translated.[value]`to access translated values, to make sure you will always get a valid translation or fallback value.
+**Example:** You instruct Shopware to fetch the French translation of a product using the `sw-language-id` header, but there's no French translation for the product's name. The resulting field `product.name` will be `null`. When building applications, always use `product.translated.[value]` to access translated values, ensuring you always get a valid translation or a fallback value.
:::
## sw-version-id
-Shopware 6 allows developers to create multiple versions of an entity. This has been used, for example, for orders. This allows relations, like documents, to pin a specific state of the entity it relates to. However, the API initially only delivers the data of the most recent record. To tell the API that a specific version should be returned, the header `sw-version-id` must be sent along with the request.
+Shopware 6 allows developers to create multiple versions of an entity. This has been used, for example, for orders. This allows relations, like documents, to pin a specific state of the entity they relate to. However, the API initially returns only the data for the most recent record. To tell the API which version to return, the header `sw-version-id` must be included with the request.
```bash
POST /api/search/order
@@ -33,7 +33,7 @@ POST /api/search/order
## sw-inheritance
-Shopware 6 allows developers to define inheritance \(parent-child\) relationships between entities of the same type. This has been used, for example, for products and their variants. Certain fields of a variant can therefore inherit the data from the parent product or define \(i.e. override\) them themselves. However, the API initially only delivers the data of its own record, without considering parent-child inheritance. To tell the API that the inheritance should be considered, the header `sw-inheritance` must be sent along with the request.
+Shopware 6 allows developers to define inheritance \(parent-child\) relationships between entities of the same type. This has been used, for example, for products and their variants. Specific fields of a variant can therefore inherit the data from the parent product or define \(i.e., override\) them themselves. However, the API initially only returns data for its own record, without considering parent-child inheritance. To tell the API that the inheritance should be considered, the header `sw-inheritance` must be sent along with the request.
```bash
POST /api/search/product
@@ -42,7 +42,7 @@ POST /api/search/product
## sw-skip-trigger-flow
-Flows are an essential part of Shopware and are triggered by events like the creation of a customer. When migrating from another e-commerce platform to shopware, you might import hundreds of thousands of customers via the sync API. In that case, you don't want to trigger the `send email on customer creation` flow. To avoid this behavior, you can pass the `sw-skip-trigger-flow` header.
+Flows are an essential part of Shopware and are triggered by events such as customer creation. When migrating from another ecommerce platform to shopware, you might import hundreds of thousands of customers via the sync API. In that case, you don't want to trigger the `send email on customer creation` flow. To avoid this behavior, you can pass the `sw-skip-trigger-flow` header.
```bash
POST /api/_action/sync
@@ -51,7 +51,7 @@ POST /api/_action/sync
## sw-access-token
-Any request to the Store API needs an Authentication with a `sw-access-token`. Refer to [Authentication & Authorization](https://shopware.stoplight.io/docs/store-api/8e1d78252fa6f-authentication-and-authorisation) section of Store API for more details on this.
+Any request to the Store API requires authentication with a `sw-access-token`. Refer to [Authentication & Authorization](https://shopware.stoplight.io/docs/store-api/8e1d78252fa6f-authentication-and-authorisation) section of Store API for more details on this.
## sw-context-token
@@ -59,7 +59,7 @@ The `sw-context-token` is used to recognize your customers in the context of the
## sw-currency-id
-When calling the API, a client can include the `sw-currency-id` header to indicate the currency in which it wants to receive prices. For example, if the header is set to "USD," the API might respond with prices converted to U.S. dollars. This header is associated with the currency settings in the admin panel. It allows clients to dynamically switch between different currencies based on their preferences.
+When calling the API, a client can include the `sw-currency-id` header to indicate the currency in which it wants to receive prices. For example, if the header is set to "USD," the API might respond with prices converted to U.S. dollars. This header is associated with the currency settings in the admin panel. It allows clients to switch between currencies based on their preferences dynamically.
```bash
POST /api/search/order
@@ -68,7 +68,7 @@ POST /api/search/order
## sw-include-seo-urls
-This header indicates whether SEO-friendly URLs for products or categories should be included in the API response. If an API request is made and the `sw-include-seo-urls` header is set, the API response will include all the configured SEO URLs for the specified product. This can provide additional information to the client about the various SEO-friendly paths associated with the product, allowing for better SEO management or customization.
+This header indicates whether SEO-friendly URLs for products or categories should be included in the API response. If an API request is made and the `sw-include-seo-urls` header is set, the API response will include all the configured SEO URLs for the specified product. This can provide the client with additional information about the various SEO-friendly paths associated with the product, enabling better SEO management or customization.
```bash
POST /api/search/product
@@ -77,7 +77,7 @@ POST /api/search/product
## sw-app-integration-id
-The `sw-app-integration-id` enables seamless connection and data exchange between different software components. This header is required for correct permission checks performed by the backend when fetching or manipulating data. It overrides the default behavior and uses the privileges provided by the app. This is used in the Meteor Admin SDK for the [Repository Data Handling](/resources/admin-extension-sdk/api-reference/data/repository). But the developer itself doesn’t need to care about it because it is handled automatically by the admin.
+The `sw-app-integration-id` enables seamless connection and data exchange between different software components. This header is required for correct permission checks performed by the backend when fetching or manipulating data. It overrides the default behavior and uses the privileges provided by the app. This is used in the Meteor Admin SDK for the [Repository Data Handling](/resources/admin-extension-sdk/api-reference/data/repository). But the developer itself doesn’t need to worry about it, since it is handled automatically by the admin.
## sw-app-user-id
diff --git a/guides/integrations-api/general-concepts/search-criteria.md b/guides/development/integrations-api/general-concepts/search-criteria.md
similarity index 68%
rename from guides/integrations-api/general-concepts/search-criteria.md
rename to guides/development/integrations-api/general-concepts/search-criteria.md
index dfa1a37f6d..7402193128 100644
--- a/guides/integrations-api/general-concepts/search-criteria.md
+++ b/guides/development/integrations-api/general-concepts/search-criteria.md
@@ -7,9 +7,7 @@ nav:
# Search Criteria
-## Overview
-
-Generally, we refer to the endpoints that use `POST` method and receive the criteria as a JSON object as **search criteria**. It takes the same arguments as a [DAL criteria](../../plugins/plugins/framework/data-handling/reading-data#filtering). Some endpoints expect more parameters than specified here. However, these differ from one endpoint to another, so we don't specify them here.
+Generally, we refer to the endpoints that use the `POST` method and receive the criteria as a JSON object as **search criteria**. It takes the same arguments as a [DAL criteria](../../../plugins/plugins/framework/data-handling/reading-data#filtering). Some endpoints require additional parameters beyond those specified here. However, these differ from one endpoint to another, so we don't specify them here.
A typical **search criteria** looks like this:
@@ -24,9 +22,9 @@ A typical **search criteria** looks like this:
"associations": {
"productOptions": {},
"group": {}
- }
- }
- },
+ }
+ }
+ },
"includes": {
"product": [
"calculatedPrice",
@@ -37,31 +35,31 @@ A typical **search criteria** looks like this:
"manufacturer",
"propertyIds",
"options"
- ],
+ ],
"product_media": [
"media"
- ],
+ ],
"media": [
"thumbnails",
"width",
"height",
"url"
- ],
+ ],
"calculated_price": [
"unitPrice",
"quantity"
- ]
- }
+ ]
+ }
}
```
-In the following, we will go through different parameters that criteria can be assembled from.
+In the following, we will go through the different parameters that can be used to assemble criteria.
| Parameter | Usage |
| :--- | :--- |
-| `associations` | Allows to load additional data to the standard data of an entity |
+| `associations` | Allows loading additional data to the standard data of an entity |
| `includes` | Restricts the output to the defined fields |
-| `ids` | Limits the search to a list of Ids |
+| `ids` | Limits the search to a list of IDs |
| `total-count-mode` | Defines whether a total must be determined |
| `page` | Defines at which page the search result should start |
| `limit` | Defines the number of entries to be determined |
@@ -71,13 +69,13 @@ In the following, we will go through different parameters that criteria can be a
| `term` | Enables you to determine a ranking for the search result |
| `sort` | Defines the sorting of the search result |
| `aggregations` | Specify aggregations to be computed on-the-fly |
-| `grouping` | Lets you group records by fields |
+| `grouping` | Let's you group records by fields |
## Parameters
### `associations`
-The `associations` parameter allows you to load additional data to the minimal data set of an entity without sending an extra request similar to a SQL Join. The parameter's key is the association's property name in the entity. You can pass nested criteria just for that association, e.g., to perform a sort to or apply filters within the association.
+The `associations` parameter allows you to load additional data to the minimal data set of an entity without sending an extra request, similar to a SQL Join. The parameter's key is the association's property name in the entity. You can pass nested criteria just for that association, e.g., to perform a sort or apply filters within the association.
```json
{
@@ -85,13 +83,13 @@ The `associations` parameter allows you to load additional data to the minimal d
"products": {
"limit": 5,
"filter": [
- { "type": "equals", "field": "active", "value": true }
- ],
+ { "type": "equals", "field": "active", "value": true }
+ ],
"sort": [
- { "field": "name", "order": "ASC" }
- ]
- }
- }
+ { "field": "name", "order": "ASC" }
+ ]
+ }
+ }
}
```
@@ -99,7 +97,7 @@ The `associations` parameter allows you to load additional data to the minimal d
The `includes` parameter allows you to restrict the returned fields.
-* Transfer only what you need reduces response payload.
+* Transfer only what you need to reduce the response payload.
* Easier to consume for client applications.
* When debugging, the response is smaller, and you can concentrate on the essential fields.
@@ -107,34 +105,34 @@ The `includes` parameter allows you to restrict the returned fields.
{
"includes": {
"product": ["id", "name"]
- }
+ }
}
// Response
{
"total": 120,
"data": [
- {
+ {
"name": "Synergistic Rubber Fish Soda",
"id": "012cd563cf8e4f0384eed93b5201cc98",
"apiAlias": "product"
- },
- {
+ },
+ {
"name": "Mediocre Plastic Ticket Lift",
"id": "075fb241b769444bb72431f797fd5776",
"apiAlias": "product"
- }
- ]
+ }
+ ]
}
```
::: info
-All response types come with a `apiAlias` field which you can use to identify the type in your includes field. If you only want a categories id, add: `"category": ["id"]`. For entities, this is the entity name: `product`, `product_manufacturer`, `order_line_item`, ... For other non-entity types like a listing result or a line item, check the full response. This pattern applies not only to simple fields but also to associations.
+All response types include an `apiAlias` field that you can use to identify the type in your includes field. If you only want a category's ID, add: `"category": ["id"]`. For entities, this is the entity name: `product`, `product_manufacturer`, `order_line_item`, ... For other non-entity types like a listing result or a line item, check the complete response. This pattern applies not only to simple fields but also to associations.
:::
### `ids`
-If you want to perform a simple lookup using just the ids of records, you can pass a list of those using the `ids` field:
+If you want to perform a simple lookup using just the IDs of records, you can pass a list of those using the `ids` field:
```json
{
@@ -142,20 +140,20 @@ If you want to perform a simple lookup using just the ids of records, you can pa
"012cd563cf8e4f0384eed93b5201cc98",
"075fb241b769444bb72431f797fd5776",
"090fcc2099794771935acf814e3fdb24"
- ]
+ ]
}
```
### `total-count-mode`
-The `total-count-mode` parameter can be used to define whether the total for the total number of hits should be determined for the search query. This parameter supports the following values:
+The `total-count-mode` parameter can be used to define whether the total number of hits should be determined for the search query. This parameter supports the following values:
* `0 [default]` - No total is determined.
* Advantage: This is the most performing mode because MySQL Server does not need to run the `SQL_CALC_FOUND_ROWS` in the background.
* Purpose: Should be used if pagination is not required.
* `1` - An exact total is determined.
* Purpose: Should be used if a pagination with the exact page number has to be displayed.
- * Disadvantage: Performance intensive. Here you have to work with `SQL_CALC_FOUND_ROWS`.
+ * Disadvantage: Performance intensive. Here, you have to use `SQL_CALC_FOUND_ROWS`.
* `2` - It is determined whether there is a next page.
* Advantage: Good performance, same as `0`.
* Purpose: Can be used well for infinite scrolling because, with infinite scrolling, the information is enough to know if there is a next page to load.
@@ -179,9 +177,9 @@ The `page` and `limit` parameters can be used to control pagination. The `page`
### `filter`
-The `filter` parameter allows you to filter the result and aggregations using many filters and parameters. The filter types are equivalent to the filters available for the DAL.
+The `filter` parameter allows you to filter results and aggregations using multiple filters and parameters. The filter types are equivalent to the filters available for the DAL.
-<PageRef page="../../../resources/references/core-reference/dal-reference/filters-reference" />
+<PageRef page="../../../../resources/references/core-reference/dal-reference/filters-reference" />
::: info
When you are filtering for nested values - for example, you are filtering orders by their transaction state \(`order.transactions.stateMachineState`\) - make sure to fetch those in your `associations` field before.
@@ -193,44 +191,44 @@ When you are filtering for nested values - for example, you are filtering orders
"transactions": {
"associations": {
"stateMachineState": {}
- }
- }
- },
+ }
+ }
+ },
"filter": [
- {
+ {
"type": "multi",
"operator": "and",
"queries": [
- {
+ {
"type": "multi",
"operator": "or",
"queries": [
- {
+ {
"type": "equals",
"field": "transactions.stateMachineState.technicalName",
"value": "paid"
- },
- {
+ },
+ {
"type": "equals",
"field": "transactions.stateMachineState.technicalName",
"value": "open"
- }
- ]
- },
- {
+ }
+ ]
+ },
+ {
"type": "equals",
"field": "customFields.exportedFlag",
"value": null
- }
- ]
- }
- ]
+ }
+ ]
+ }
+ ]
}
```
### `post-filter`
-Work the same as `filter`; however, they don't apply to aggregations. This is great when you want to work with aggregations to display facets for filter navigation but already filter results based on filters without making an additional request.
+Works the same as `filter`; however, they don't apply to aggregations. This is great when you want to work with aggregations to display facets for filter navigation, but already filter results based on filters without making an additional request.
### `query`
@@ -239,23 +237,23 @@ Use this parameter to create a weighted search query that returns a `_score` for
```json
{
"query": [
- {
+ {
"score": 500,
"query": { "type": "contains", "field": "name", "value": "Bronze"}
- },
- {
+ },
+ {
"score": 500,
"query": { "type": "equals", "field": "active", "value": true }
- },
- {
+ },
+ {
"score": 100,
"query": {
"type": "equals",
"field": "manufacturerId",
"value": "db3c17b1e572432eb4a4c881b6f9d68f"
- }
- }
- ]
+ }
+ }
+ ]
}
```
@@ -265,46 +263,46 @@ The resulting score is appended to every resulting record in the `extensions.sea
{
"total": 5,
"data": [
- {
+ {
"manufacturerId": "db3c17b1e572432eb4a4c881b6f9d68f",
"name": "Awesome Bronze Krill Kream",
"extensions": {
"search": {
"_score": "1100"
- }
- },
+ }
+ },
"id": "0acc3aa5c45a492c9a2adb8844cb7adc",
"apiAlias": "product"
- },
- {
+ },
+ {
"manufacturerId": "d0c0daa910d94b3c8b03c2bef6acb9b8",
"name": "Synergistic Bronze New Tab",
"extensions": {
"search": {
"_score": "1000"
- }
- },
+ }
+ },
"id": "72858576ac634f209b7ad61db15b7cc3",
"apiAlias": "product"
- },
- {
+ },
+ {
"manufacturerId": "3b5f9d51803849c68bb72360debd3da0",
"name": "Fantastic Paper Zamox",
"extensions": {
"search": {
"_score": "500"
- }
- },
+ }
+ },
"id": "18d2b4225ea34b17a6099108da159e7f",
"apiAlias": "product"
- }
- ]
+ }
+ ]
}
```
### `term`
-Using the `term` parameter, the server performs a text search on all records based on their data model and weighting as defined in the entity definition using the `SearchRanking` flag.
+Using the `term` parameter, the server performs a text search across all records based on their data model and weighting, as defined in the entity definition, using the `SearchRanking` flag.
::: info
Don't use `term` parameters together with `query` parameters.
@@ -332,16 +330,16 @@ The `sort` parameter allows controlling the sorting of the result. Several sorts
{
"limit": 5,
"sort": [
- { "field": "name", "order": "ASC", "naturalSorting": true },
- { "field": "active", "order": "DESC" },
- { "field": "products.id", "order": "DESC", "type": "count" }
- ]
+ { "field": "name", "order": "ASC", "naturalSorting": true },
+ { "field": "active", "order": "DESC" },
+ { "field": "products.id", "order": "DESC", "type": "count" }
+ ]
}
```
### `count` sorting behavior
-For demonstration purposes, see the following request payload that additionally includes a `count` aggregation.
+For demonstration purposes, see the following request payload, which also includes a `count` aggregation.
::: info
This `count` type was introduced with Shopware 6.4.12.0 and is not available in prior versions.
@@ -352,12 +350,12 @@ This `count` type was introduced with Shopware 6.4.12.0 and is not available in
"limit": 3,
"includes": {
"product": ["id"]
- },
+ },
"sort": [
- { "field": "categories.id", "order": "DESC", "type": "count" }
- ],
+ { "field": "categories.id", "order": "DESC", "type": "count" }
+ ],
"aggregations": [
- {
+ {
"name": "product-id",
"type": "terms",
"field": "id",
@@ -367,9 +365,9 @@ This `count` type was introduced with Shopware 6.4.12.0 and is not available in
"name": "category-count",
"type": "count",
"field": "product.categories.id"
- }
- }
- ]
+ }
+ }
+ ]
}
```
@@ -381,53 +379,53 @@ In response, the order of the `product` elements is now equal to the order of th
"aggregations": {
"product-id": {
"buckets": [
- {
+ {
"key": "f977f6a845a54b0381cbaf322f53b63e",
"count": 5
- },
- {
+ },
+ {
"key": "8d0ee52433df44b78a6f7827180049d9",
"count": 4
- },
- {
+ },
+ {
"key": "003a9df163474b28bc8a000243549547",
"count": 3
- }
- ]
- }
- },
+ }
+ ]
+ }
+ },
"elements": [
- { "id": "f977f6a845a54b0381cbaf322f53b63e" },
- { "id": "8d0ee52433df44b78a6f7827180049d9" },
- { "id": "003a9df163474b28bc8a000243549547" }
- ]
+ { "id": "f977f6a845a54b0381cbaf322f53b63e" },
+ { "id": "8d0ee52433df44b78a6f7827180049d9" },
+ { "id": "003a9df163474b28bc8a000243549547" }
+ ]
}
```
## `aggregations`
-The `aggregations` parameter can determine metadata for a search query. There are different types of aggregations that are listed in the reference documentation. A simple example is the determination of the average price from a product search query.
+The `aggregations` parameter can determine metadata for a search query. There are different types of aggregation listed in the reference documentation. A simple example is the determination of the average price from a product search query.
* Purpose: Calculation of statistics and metrics.
* Purpose: Determination of possible filters.
The aggregation types are equivalent to the aggregations available in the DAL:
-<PageRef page="../../../resources/references/core-reference/dal-reference/aggregations-reference" />
+<PageRef page="../../../../resources/references/core-reference/dal-reference/aggregations-reference" />
```json
{
"limit": 1,
"includes": {
"product": ["id", "name"]
- },
+ },
"aggregations": [
- {
+ {
"name": "average-price",
"type": "avg",
"field": "price"
- }
- ]
+ }
+ ]
}
```
diff --git a/guides/development/integrations-api/index.md b/guides/development/integrations-api/index.md
new file mode 100644
index 0000000000..4bf434c911
--- /dev/null
+++ b/guides/development/integrations-api/index.md
@@ -0,0 +1,79 @@
+---
+nav:
+ title: Working with APIs
+ position: 40
+
+---
+
+# Working with APIs
+
+Shopware provides two HTTP APIs:
+
+* [Admin API](https://shopware.stoplight.io/docs/admin-api/twpxvnspkg3yu-quick-start-guide)
+* [Store API](https://shopware.stoplight.io/docs/store-api/38777d33d92dc-quick-start-guide).
+
+These APIs serve different purposes but share common principles and infrastructure.
+
+## Admin API
+
+Primarily for backend and administrative functions, the Admin API enables structured data exchange, bulk operations, data synchronization, and import/export.
+
+Use it when:
+
+* Managing entities (products, categories, orders)
+* Running backend integrations
+* Performing bulk operations
+* Building admin-side applications
+
+Complete endpoint documentation (local instance required): `/api/_info/stoplightio.html`.
+
+Search endpoints use: `POST /api/search/{entity}`
+
+## Store API
+
+This customer-facing API allows you to access and manipulate data related to products, customer interactions, shopping carts, and other aspects of Shopware that significantly impact the frontend user experience. It serves both anonymous and authenticated users.
+
+Use it when:
+
+* Interacting with products and listings
+* Managing carts and checkout
+* Building headless storefronts
+* Serving anonymous or authenticated customers
+
+Complete endpoint documentation (local instance required): `/store-api/_info/stoplightio.html`
+
+## Shared API mechanics
+
+Both APIs use the same foundational structures:
+
+* [Search Criteria](./general-concepts/search-criteria.md): encapsulates the entire search definition in one generic object
+* [Request Headers](./general-concepts/request-headers.md): additional instructions
+* [Partial Data Loading](./general-concepts/partial-data-loading.md)
+
+These define how data is filtered, structured, and versioned.
+
+For architectural background, see the [API overview](./../../../concepts/api/index.md).
+
+## Generated API reference
+
+### OpenAPI schema
+
+Shopware exposes OpenAPI schemas for both Admin API and Store API. These schemas are generated via PHP annotations using [swagger-php](https://github.com/zircote/swagger-php). If you build custom endpoints, you can leverage these annotations to generate standardized documentation for them.
+
+::: warning
+Due to security restrictions, your **`APP_ENV`** environment variable must be set to **`dev`** to access the specifications described below.
+:::
+
+To retrieve the raw schema definition directly, use the following endpoint:
+
+```text
+/(api|store-api)/_info/openapi3.json
+```
+
+### Entity schema
+
+To access the schema definitions of all available entities instead of an endpoint reference, use one of the corresponding schema endpoints instead:
+
+```text
+/(api|store-api)/_info/open-api-schema.json
+```
diff --git a/guides/plugins/apps/in-app-purchases.md b/guides/development/monetization/in-app-purchases.md
similarity index 80%
rename from guides/plugins/apps/in-app-purchases.md
rename to guides/development/monetization/in-app-purchases.md
index 8bc9a09b18..0af7f9ba63 100644
--- a/guides/plugins/apps/in-app-purchases.md
+++ b/guides/development/monetization/in-app-purchases.md
@@ -11,7 +11,7 @@ nav:
In-App Purchase is available since Shopware version 6.6.9.0
:::
-In-App Purchases are a way to lock certain features behind a paywall within the same extension.
+In-App Purchases allow you to lock certain features behind a paywall within the same extension.
This is useful for developers who want to offer a free version of their extension with limited features and a paid version with more features.
<PageRef page="../../../concepts/framework/in-app-purchases" title="In-App purchases concept" />
@@ -19,32 +19,32 @@ This is useful for developers who want to offer a free version of their extensio
## Allow users to buy an In-App Purchase
-In order to enable others to purchase your In-App Purchase, you must request a checkout for it via the `sw.iap.purchase()` function of the [Meteor Admin SDK](https://github.com/shopware/meteor/tree/main/packages/admin-sdk).
+To enable others to purchase your In-App Purchase, you must request a checkout for it via the `sw.iap.purchase()` function of the [Meteor Admin SDK](https://github.com/shopware/meteor/tree/main/packages/admin-sdk).
The checkout process itself is provided by Shopware.
As this is purely functional, it is your responsibility to provide a button and hide it if the IAP cannot be purchased more than once.
```vue
<template>
- <!-- ... -->
- <p>
- If you buy this you'll get an incredible useful feature: ...
- </p>
- <mt-button @click="onClick">
- Buy
- </mt-button>
- <!-- ... -->
+ <!-- ... -->
+ <p>
+ If you buy this you'll get an incredible useful feature: ...
+ </p>
+ <mt-button @click="onClick">
+ Buy
+ </mt-button>
+ <!-- ... -->
</template>
<script setup>
import * as sw from '@shopware/meteor-admin-sdk';
function onClick() {
- sw.iap.purchase({ identifier: 'my-iap-identifier' });
+ sw.iap.purchase({ identifier: 'my-iap-identifier' });
}
</script>
```
-Alternatively, you can trigger a checkout manually by sending a properly formatted
+Alternatively, you can trigger a checkout manually by sending a properly formatted.
[post message](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) with an In-App purchase identifier to the Admin.
## Check active In-App Purchases
@@ -54,8 +54,7 @@ Whenever Shopware sends you a request, you'll receive a [JWT](../../../concepts/
### Symfony or PHP app servers
You can use the `shopware/app-php-sdk` for plain PHP or the `shopware/app-bundle` for Symfony to validate and decode the JWT.
-An example for plain PHP is available [here](https://github.com/shopware/app-php-sdk/blob/main/examples/index.php).
-For Symfony applications, use the appropriate action argument for your route.
+Refer to an [example for plain PHP](https://github.com/shopware/app-php-sdk/blob/main/examples/index.php). For Symfony applications, use the appropriate action argument for your route.
#### Admin
@@ -69,7 +68,7 @@ Here is an example of retrieving active In-App Purchases in an example `admin.ht
public function admin(ModuleAction $action): Response {
return $this->render('admin.html.twig', [
'inAppPurchases' => $action->inAppPurchases->all(),
- ]);
+ ]);
}
```
@@ -80,10 +79,10 @@ public function admin(ModuleAction $action): Response {
<script>
try {
window.inAppPurchases = JSON.parse('{{ inAppPurchases | json_encode | raw }}');
- } catch (e) {
+ } catch (e) {
window.inAppPurchases = {};
console.error('Unable to decode In-App Purchases', e);
- }
+ }
</script>
<!-- ... -->
@@ -115,4 +114,4 @@ console.log(payload); // Contains list of purchased IAP identifiers
## Event
Apps are also able to manipulate the available In-App Purchases as described in
-<PageRef page="./gateways/in-app-purchase/in-app-purchase-gateway" title="In App purchase gateway" />
+<PageRef page="../../plugins/apps/gateways/in-app-purchase/in-app-purchase-gateway" title="In App purchase gateway" />
diff --git a/guides/development/monetization/index.md b/guides/development/monetization/index.md
new file mode 100644
index 0000000000..a3782260d2
--- /dev/null
+++ b/guides/development/monetization/index.md
@@ -0,0 +1,24 @@
+---
+nav:
+ title: Monetization
+ position: 10
+
+---
+
+# Monetization
+
+Shopware provides multiple ways to monetize your extension in the Store. Choose the model that fits your business strategy and target audience.
+
+All monetized extensions must comply with our [quality guidelines](./quality-guidelines) and avoid [Common Store Review Errors](./store-review-errors).
+
+## Paid extensions
+
+Sell your extension with a one-time purchase or subscription model via the Shopware Store. Pricing and licensing are managed in your Shopware Account.
+
+## In-App Purchases (IAP)
+
+[In-App Purchases](./in-app-purchases) enable locking specific features behind additional purchases within the same extension. Available since Shopware 6.6.9.0.
+
+## Commission-based integrations
+
+If your extension integrates external services and generates revenue (e.g., transaction-based fees), a Shopware Technology Partner (STP) agreement may be required. See the [quality guidelines](./quality-guidelines) for details.
diff --git a/guides/development/monetization/quality-guidelines.md b/guides/development/monetization/quality-guidelines.md
new file mode 100644
index 0000000000..09b523c6ee
--- /dev/null
+++ b/guides/development/monetization/quality-guidelines.md
@@ -0,0 +1,327 @@
+---
+nav:
+ title: Quality Guidelines for Store Extensions
+ position: 20
+
+---
+
+# Quality Guidelines for Store Extensions
+
+These guidelines apply to all extensions distributed via the Shopware Store, including both plugins and apps. They define the quality, security, and compliance requirements for publication.
+
+## Scope and terminology
+
+* **Extension**: umbrella term for plugins and apps.
+* **Plugin**: installed in the Shopware instance; PHP code, Composer.
+* **App**: integrated via app system; no direct PHP execution in core.
+
+Unless stated otherwise, requirements apply to all extensions.
+
+## Review process
+
+All extensions are:
+
+1. Automatically [code-reviewed](https://github.com/shopwareLabs/store-plugin-codereview) (PHPStan, SonarQube), due to our quality assurance, with special attention on impacts to the Administration and Storefront.
+2. Manually reviewed for security, coding standards, user experience, and functionality.
+3. Tested on the latest stable [Shopware 6](https://www.shopware.com/de/download/#shopware-6) CE version.
+
+Always test against the highest supported Shopware 6 version (e.g., `shopware/testenv:6.7.6`).
+
+For apps, we additionally test:
+
+* `config.xml` per sales channel
+* Install/uninstall behavior
+* Styling and viewport issues
+
+Before publishing an extension, review the full test process to ensure fast approval.
+
+::: info
+[Test your app for the Shopware Store (DE):](https://www.youtube.com/watch?v=gLb5CmOdi4g); EN version is coming soon.
+:::
+
+## Store listing requirements
+
+All extensions must:
+
+* Be available in English, with 1:1 translation between English and German. For the German store, German language is required. All extensions will be released in both the German and International stores.
+* Use meaningful short and long descriptions.
+ * The short description (150–185 characters) teases your extension in an overview, along with "Customers also bought" and "Customers also viewed" recommendations. It is also published as a meta-description.
+ * Long descriptions (minimum 200 characters) must describe the extension's functionality in detail.
+* Accurately and clearly describe the extension and its use cases.
+* Avoid the words “plugin” and “shopware” in the display name.
+* Avoid blank spaces as filler text.
+* Include clear, complete setup and configuration instructions.
+* Use clean HTML source code. Inline styles will be stripped.
+
+These tags are allowed:
+
+```markdown
+<a> <p> <br> <b> <strong> <i> <ul> <ol> <li> <h2> <h3> <h4> <h5>
+```
+
+### Fallback language/translations
+
+Extensions must work independently of the system language.
+
+If a translation is missing (e.g., Spanish), a proper fallback (usually English) must be used.
+
+If your extension is available in multiple languages, define them in your Shopware Account under “Translations into the following languages are available,” located in the "Description & images" section.
+
+We review:
+
+* Text snippets
+* `config.xml`
+* `composer.json`
+
+### Reserve your extension name with a store preview
+
+To secure an idea early, create a preview in your Shopware Account. Request this by providing placeholder images, meaningful use cases, key features, a description, and an expected release month. No binary upload is required.
+
+### Extension master data/license
+
+The license selected in your Shopware Account must match the license defined in `composer.json`. The selected license cannot be changed after the extension has been created. Changes require creating a new extension with a new technical name and uploading it again.
+
+## Screenshots and media requirements
+
+* Use English-only screenshots for the English store listing and preview images.
+* Screenshots in German for the German store description are optional.
+* Only images that represent or show the function of the extension are permissible.
+* Advertising for other extensions or services is not permitted.
+* Ensure that screenshots show the extension's functionality in action in the Storefront and administration, as well as configuration options and how-to-use details.
+* We recommend screenshots showing mobile and desktop views.
+
+:::info
+[How To - Add images and icons to extensions](https://docs.shopware.com/en/account-en/adding-pictures-and-icons/how-to)
+:::
+
+## Preview requirements
+
+* A preview image must be available in the Extension Manager.
+* Store a valid favicon named `plugin.png` (112x112px) under `src/Resources/config/`. This favicon will help you identify your extension in the `Administration > Extension Manager` module.
+* [Themes](../../plugins/themes/index.md) require a preview image in the Theme Manager.
+* [Shopping World elements](../../../concepts/commerce/content/shopping-experiences-cms.md#elements) must include an element icon.
+
+Read our [How to request a preview](https://docs.shopware.com/en/account-en/extension-partner/extensions?category=account-en/extension-partner#how-can-i-request-a-preview) guide for additional help.
+
+## Demo shop requirements
+
+* URLs must not contain `http:` or `https:`.
+* Test environments will be automatically deleted after two weeks, so do not link to them.
+
+## Manufacturer profile requirements
+
+The manufacturer profile exists in your account under Shopware Account > Extension Partner > [Extension Partner profile](https://account.shopware.com/producer/profile).
+
+* A manufacturer logo is required.
+* No iframes, tracking, or external scripts are allowed.
+* External sources must use HTTPS.
+* Must contain accurate English and German descriptions.
+
+::: info
+The source code's descriptions, profiles, and instructions do not allow iframes, external scripts, or tracking pixels. Custom styles may not overwrite the original Shopware styles. External sources must be included via https.
+:::
+
+::: info
+You can no longer advertise Shopware certificates within an extension's description, images, or your manufacturer profile.
+Manufacturer/partner certificates are dynamically loaded at the end of each extension description and published by Shopware.
+:::
+
+## Data Protection
+
+If the personal data of customers, including store operators and their customers, is processed according to Art. 28 DSGVO:
+
+* Subprocessor information must be declared.
+* Additional processors must be listed accordingly, under "further subprocessors."
+
+An extension with a name that directly reflects its functional purpose is permissible, even if it shares the same name as another extension.
+
+The store display name must be used for `composer.json` and `config.xml`.
+
+Not allowed:
+
+* Inline styles.
+* Certificates in descriptions.
+* Iframes, tracking pixels, external scripts.
+
+We allow up to two YouTube videos embedded in your extension description.
+
+:::info
+Video content—especially explainer videos, product demos, and tutorials—increases awareness and trust and has proven to convert potential customers better than other content types.
+:::
+
+## Functional requirements
+
+All extensions must:
+
+* Work without 500 errors.
+* Avoid 400 errors unless they are related to an API call.
+* Be installable and uninstallable without issues.
+* During uninstall, users must be able to choose in the Extension Manager whether to "completely delete or "keep the app data, text snippets, media folder, including own media and table adjustments." The free [Adminer](https://store.shopware.com/en/frosh79014577529f/adminer-for-admin.html) extension from Friends of Shopware enables you to do this via your provided test environment.
+* Avoid extending or overwriting the Extension Manager.
+* Properly register cookies in the [Cookie Consent Manager](../../../guides/plugins/plugins/storefront/add-cookie-to-manager).
+ * Every cookie set from the store URL should be optional and not technically required for running Shopware. We differentiate between "Technically required", "Marketing," and "Comfort features."
+ * All cookies must appear (unchecked) in the cookie configuration box in the frontend.
+* Do not introduce severe performance regressions.
+* Do not break Storefront SEO, structured data, or canonical logic.
+* If the extension publishes messages to the message queue, each message must not exceed 262,144 bytes (256 KB). This limitation is set by common message queue workers.
+* After uninstalling the extension, Shopping Experiences must continue to work in the frontend.
+
+### Plugin-specific requirements
+
+These apply only to plugins:
+
+* [Composer dependencies](../../../guides/plugins/plugins/plugin-fundamentals/using-composer-dependencies) must be declared in `composer.json` so they are traceable.
+ * If `executeComposerCommands() === true` is used, dependencies are installed dynamically and do not need to be bundled.
+* `composer.lock` must not be included in the archive.
+* Deliver uncompiled (readable) JavaScript in addition to compiled assets. Uncompiled sources must be included in a separate folder to allow code review.
+ * Build `main.js` and create the minified code according to our documentation: [Loading the JS files](../../../guides/plugins/plugins/administration/module-component-management/add-custom-field.md#loading-the-js-files) and [Injecting into the Administration](../../../guides/plugins/plugins/administration/module-component-management/add-custom-field.md#injecting-into-the-administration).
+* Only production files may be included in the archive.
+* Unified logs must be written to `/var/log/`.
+* No forbidden PHP statements like `die`, `exit`, or `var_dump` are allowed. See [List of blockers](https://s3.eu-central-1.amazonaws.com/wiki-assets.shopware.com/1657519735/blocker.txt)
+* Shopware must have access to the unminified source code of the extension at all times.
+
+### App-specific requirements
+
+These apply only to apps:
+
+* Per-sales-channel configuration required if using `config.xml``.
+* No loading external files during installation.
+* API integrations must include an API test button.
+* Must not modify Extension Manager.
+* STP agreement required for commission-based integrations.
+* Apps that appear in the Storefront and use a `config.xml` must be able to be configured separately for each sales channel.
+
+## Code and security requirements
+
+* Pass automated code reviews (PHPStan, SonarQube).
+* Do not include development files or unused resources in the binary.
+* Include only necessary dependencies.
+* Use secure cookie settings.
+
+## Composer and dependencies
+
+If the extension includes Composer dependencies:
+
+* All delivered code must be traceable via Composer.
+* The extension must not exceed store size limits.
+
+## Storefront guidelines
+
+* No inline CSS allowed in storefront templates. Use your own classes and let your CSS be compiled by the plugin. See [Add SCSS variables](../../../guides/plugins/plugins/storefront/add-scss-variables.md#add-scss-variables).
+* Avoid using the `!important` rule unless unavoidable.
+* All images must include meaningful `alt` tags, or original `alt` tags from the media manager.
+* All links must include meaningful `title` tags.
+* External links must use `target="_blank"` together with `rel="noopener"`.
+* No `<hX>` tags in the storefront templates, which are set to `<meta name="robots" content="index,follow">`. These are reserved exclusively for content purposes.
+ * However, you may employ `<span class="h2">`, for instance.
+* Performance should remain stable (Lighthouse A/B check recommended).
+* Test the frontend and the checkout for new errors throughout the entire Storefront using the Browser Debug Console, paying close attention to JavaScript errors.
+
+## SEO & indexing requirements
+
+* New controller URLs or XHR requests must include the header `X-Robots-Tag: noindex, nofollow`. See [robots meta tag](https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag?hl=de#xrobotstag) documentation for additional guidance.
+* Public frontend URLs created by the extension must appear in `sitemap.xml` and include a valid canonical tag, unique meta descriptions, and `title` tags (configurable via Administration or as a text snippet).
+
+## Administration guidelines
+
+* Do not add new main menu entries in the Administration, to preserve look and feel consistency.
+* Create a dedicated media folder with correct thumbnail settings or use an existing one (except for uploads defined in `config.xml`).
+* Custom media folders and their contents must be removed during uninstall.
+* All links must include meaningful `title` tags.
+* All images must include meaningful `alt` tags, or original `alt` tags from the media manager.
+* If your API corresponds via API credentials to external services, provide an API test button. ([Example implementation](https://github.com/shyim/ShyimApiTest) in the system config form)
+* It is possible to validate required credentials while saving them in extension settings. Display a status message in the Administration and log the result in Shopware.
+* If API data is incorrect, an entry must appear in the `/var/log/` file or in the database event log.
+
+### Installation and lifecycle
+
+* The Extension Manager (Debug Console) controls installation, uninstallation, reinstallation, and deletion.
+* Install, uninstall, and reinstall must work without exceptions.
+* No 400/500 errors during install/uninstall are allowed.
+* Users must be able to choose whether to delete or keep extension data.
+* Special PHP requirements must be validated during installation.
+* If validation fails, a growl message must appear in the Administration.
+* Extensions must not modify or overwrite the Extension Manager.
+* Apps must not reload or load external files during installation.
+
+### Error messages and logging
+
+* Error or informational messages can only be recorded in the event log of Shopware's log folder, `/var/log/`.
+* Do not write to Shopware’s default logs or outside the system log directory. This ensures that the log file can never be accessed via the URL.
+* Log files must follow the naming pattern: `MyExtension-Year-Month-Day.log`.
+* Payment apps must use the "plugin logger" service.
+* If storing logs in a database, avoid using custom log tables. Otherwise, you have to implement scheduled cleanup (max retention six months).
+
+### API integrations
+
+If external APIs are used:
+
+* API test button required.
+* Credentials must be validated on save.
+* Success/failure must display a status message in Administration.
+* Errors must be logged in `/var/log/` or the database.
+
+## Commercial and external integrations
+
+If your extension integrates with external services and generates revenue (e.g., interfaces with downstream fees), a Shopware Technology Partner (STP) agreement may be required.
+
+Commission-based integrations must report usage data according to the STP contract:
+
+Every external technology extension needs to track its commission. Below is an example of implementing the tracking logic:
+
+```json
+ {
+ "identifier": "8e167662-6bbb-11eb-9439-0242ac130002",
+ "reportDate": "2005-08-15T15:52:01",
+ "instanceId": "alur24esfaw3ghk",
+ "shopwareVersion": "6.3.1",
+ "reportDataKeys": [
+ {
+ "customer": 3
+ },
+ {
+ "turnover": 440
+ }
+ ]
+ }
+```
+
+`// POST /shopwarepartners/reports/technology` allows partners to send Shopware the info based on the STP contract.
+
+If you have any questions regarding the STP agreement, please contact our sales team at [alliances@shopware.com](mailto:alliances@shopware.com) or call **+44 (0) 203 095 2445 (UK) / 00 800 746 7626 0 (worldwide) / +49 (0) 25 55 / 928 85-0 (Germany)**.
+
+**Progressive Web App:** If your app is Progressive Web App-compatible and you would like the PWA flag, please contact us at [alliances@shopware.com](mailto:alliances@shopware.com).
+
+### External fonts and services
+
+If external fonts (e.g., Google Fonts, Font Awesome) or other third-party services are used, this must be clearly stated in the store description.
+
+If personal data is transferred, update your data protection information accordingly. A tooltip in the extension configuration is recommended to inform users.
+
+## Lighthouse A/B-Testing
+
+Run a [Google Lighthouse](https://developer.chrome.com/docs/lighthouse) audit before and after activating the extension.
+
+Significant regressions in performance, accessibility, best practices, or SEO are allowed. No new console errors may be introduced.
+
+### schema.org/rich snippets A/B-testing checklist
+
+A/B testing can ensure that structured data is valid and that rich results behave correctly across page types.
+
+Use Scheme.org's [Schema Markup Validator](https://validator.schema.org/) and Google's [Rich Result Tester](https://search.google.com/test/rich-results) to check the homepage, categories, and product detail pages — including available products, unavailable products, products with no review, single review, reviews with varied ratings, out-of-stock products, products for future release, and/or any other product configuration and product types (including EAN, MPN, width, length, height, and weight). Also, check for duplicate entries and any new bugs.
+
+## Tools
+
+Use the [Shopware CLI](/development/tooling/cli) to build, validate, and upload Shopware 6 plugin releases to the Community Store. It also supports efficiently managing store descriptions and plugin images.
+
+## Final notes
+
+An extension may be rejected if:
+
+* It violates coding standards.
+* It introduces security issues.
+* It bundles unauthorized files.
+* It breaks storefront behavior.
+* It misrepresents functionality in the store description.
+
+Ensure full compliance before submission to avoid publication delays.
diff --git a/guides/development/monetization/store-review-errors.md b/guides/development/monetization/store-review-errors.md
new file mode 100644
index 0000000000..7c8e6d17c8
--- /dev/null
+++ b/guides/development/monetization/store-review-errors.md
@@ -0,0 +1,167 @@
+---
+nav:
+ title: Store Review Errors
+ position: 30
+
+---
+
+# Common Store Review Errors
+
+These errors apply to all extensions submitted to the Shopware Store (plugins and apps).
+
+## Composer and bootstrap issues
+
+### Missing or invalid `composer.json`
+
+Typical causes:
+
+* `composer.json` missing.
+* Technical name mismatch between Store and `composer.json`.
+* Wrong `extra.shopware-plugin-class`.
+* The extension archive has an incorrect ZIP structure.
+
+Check:
+
+* Store technical name matches the `composer.json` name.
+* `extra.shopware-plugin-class` points to the correct bootstrap class.
+* Namespace matches exactly (case-sensitive).
+* Archive contains correct root folder structure.
+
+Example [reference](https://github.com/FriendsOfShopware/FroshPlatformPerformance/blob/master/composer.json#L20):
+
+**Correct**: `Swag\\MyPlugin\\SwagMyPlugin`
+**Incorrect**: `Swag\\MyPlugin\\SwagMyPluginSW6`
+
+[Extension Meta Information – Explanation of the properties](../../../guides/plugins/plugins/plugin-base-guide#the-composerjson-file)
+
+### Missing bootstrap class
+
+Common causes include:
+
+* Wrong ZIP structure.
+* A typo.
+* Case-sensitive filename mismatch.
+* Namespace mismatch.
+
+### `composer.lock` Problems
+
+Rules:
+
+* `composer.lock` must NOT be included in the archive.
+* Lock file must match `composer.json` before packaging.
+* Run `composer update` if lock is outdated.
+
+## Dependency and version errors
+
+### Missing Shopware packages
+
+An example error might look like `Class Shopware\Storefront\* not found`. To fix:
+
+* Declare required packages correctly and explicitly in `composer.json`: e.g., `"require": {"shopware/frontend": "*"}`.
+* Avoid "*" version constraints. Using "*" may resolve to Early Access (EA) versions, causing review failures.
+* Use proper version ranges (e.g., `~6.1.0`).
+* If needed, set `"minimum-stability": "RC"`.
+
+This example shows the correct format:
+
+```xml
+<pre>"require": {
+
+ "shopware/core": "~6.1.0",
+
+ "shopware/storefront": "~6.1.0"
+
+},
+
+"minimum-stability": "RC"</pre>
+```
+
+### Class Not Found (EA Version Issue)
+
+In the Shopware 6 Early Access (EA) version,`Class Shopware\Core\System\Snippet\Files\SnippetFileInterface` is not found and cannot be autoloaded, causing the code review to fail.
+
+**Cause**: Composer resolved an Early Access version due to wildcard constraints.
+
+**Solution**: Pin versions and define minimum stability (see above).
+
+## Code & Static Analysis Errors
+
+### Forbidden Statements
+
+Blocked:
+
+* `die`
+* `exit`
+* `var_dump`
+
+### Invalid method usage
+
+You might see `Call to static method *jsonEncode() on an unknown class*`. Shopware always uses `json_encode()` exclusively; there is no fallback.
+
+### Remove dead code
+
+Remove out-commented code from your source code. Ensure there are no unused classes or files.
+
+## Cross-Domain Messaging
+
+Ensure that cross-document messages are sent to the intended domain. Unrestricted messaging will be rejected.
+
+Link: [OWASP Web Security Testing Guide](https://github.com/OWASP/wstg/blob/master/document/4-Web_Application_Security_Testing/11-Client-side_Testing/11-Testing_Web_Messaging.md)
+
+## Cookie and security issues
+
+Cookies must be set securely. All non-essential cookies must be registered in the Cookie Consent Manager.
+
+## Packaging errors and unauthorized files and folders
+
+Extensions submitted to the Shopware Store must not contain development files, temporary artifacts, or unused resources.
+
+* ./tests
+* .DS_Store
+* .editorconfig
+* .eslintrc.js
+* .git
+* .github
+* .gitignore
+* .gitkeep
+* .gitlab-ci.yml
+* .gitpod.Dockerfile
+* .gitpod.yml
+* .phar
+* .php-cs-fixer.cache
+* .php-cs-fixer.dist.php
+* .php_cs.cache
+* .php_cs.dist
+* .prettierrc
+* .stylelintrc
+* .stylelintrc.js
+* .sw-zip-blacklist
+* .tar
+* .tar.gz
+* .travis.yml
+* .zip
+* .zipignore
+* ISSUE_TEMPLATE.md
+* Makefile
+* Thumbs.db
+* __MACOSX
+* auth.json
+* bitbucket-pipelines.yml
+* build.sh
+* composer.lock
+* eslint.config.js
+* grumphp.yml
+* package-lock.json
+* package.json
+* phpdoc.dist.xml
+* phpstan-baseline.neon
+* phpstan.neon
+* phpstan.neon.dist
+* phpunit.sh
+* phpunit.xml.dist
+* phpunitx.xml
+* psalm.xml
+* rector.php
+* shell.nix
+* stylelint.config.js
+* webpack.config.js
diff --git a/guides/development/testing/ci.md b/guides/development/testing/ci.md
new file mode 100644
index 0000000000..6c60684adf
--- /dev/null
+++ b/guides/development/testing/ci.md
@@ -0,0 +1,35 @@
+---
+nav:
+ title: CI
+ position: 10
+
+---
+
+# CI
+
+CI should, at a minimum, run static analysis and coding standards checks alongside the project or extension build to keep artifacts reproducible. Add sanity checks, such as smoke tests and lightweight integration tests, to catch regressions early.
+
+Automated tests — unit, integration, and E2E where feasible — make refactors, upgrades, and dependency changes safer.
+
+:::info
+Follow the [Deployment guide](../../hosting/installation-updates/deployments/index.md) for information about promotion and release.
+:::
+
+## Cross-cutting practices
+
+* Fail fast on coding standards and static analysis before slower E2E tests.
+* Use the ([Shopware CLI formatter](../../../products/cli/formatter.md)) to keep code style consistent and run the bundled validation tools in CI using ([Shopware CLI validation tools](../../../products/cli/validation.md)).
+* Produce artifacts once per commit (ZIP for plugins, deployment-ready image/package for apps, built assets for projects) and promote the same artifact through stages.
+
+## Custom projects
+
+* Reuse the ([Project build command](../../../products/cli/project-commands/build.md)) to compile Storefront and Administration assets and warm caches. Run it in CI so deployments do not rebuild.
+* Use environment-specific config only in deployment, not in CI. See [setup patterns](../../installation/index.md) you can mirror in pipelines.
+* Add smoke tests against the HTTP layer plus DAL-level integration tests for custom entities.
+* Cache Composer/NPM dependencies but keep lock files committed for deterministic builds.
+
+## Custom/Store plugins
+
+* Build and validate with `shopware-cli extension build` ([Extension build command](../../products/cli/extension-commands/build.md)) to ensure the ZIP is reproducible.
+* Run unit/integration tests with the Shopware test environment; keep fixtures inside the plugin to avoid coupling to project data.
+* For Store plugins, add the Shopware Store validations early (linting, metadata, PHPStan) to catch review issues before submission ([Store submission via CLI](../../../products/cli/shopware-account-commands/releasing-extension-to-shopware-store.md)).
diff --git a/guides/plugins/plugins/testing/playwright/actor-pattern.md b/guides/development/testing/e2e-playwright/actor-pattern.md
similarity index 100%
rename from guides/plugins/plugins/testing/playwright/actor-pattern.md
rename to guides/development/testing/e2e-playwright/actor-pattern.md
diff --git a/guides/plugins/plugins/testing/playwright/best-practices.md b/guides/development/testing/e2e-playwright/best-practices.md
similarity index 100%
rename from guides/plugins/plugins/testing/playwright/best-practices.md
rename to guides/development/testing/e2e-playwright/best-practices.md
diff --git a/guides/plugins/plugins/testing/playwright/deployment.md b/guides/development/testing/e2e-playwright/deployment.md
similarity index 100%
rename from guides/plugins/plugins/testing/playwright/deployment.md
rename to guides/development/testing/e2e-playwright/deployment.md
diff --git a/guides/plugins/plugins/testing/playwright/fixtures.md b/guides/development/testing/e2e-playwright/fixtures.md
similarity index 100%
rename from guides/plugins/plugins/testing/playwright/fixtures.md
rename to guides/development/testing/e2e-playwright/fixtures.md
diff --git a/guides/plugins/plugins/testing/playwright/index.md b/guides/development/testing/e2e-playwright/index.md
similarity index 100%
rename from guides/plugins/plugins/testing/playwright/index.md
rename to guides/development/testing/e2e-playwright/index.md
diff --git a/guides/plugins/plugins/testing/playwright/install-configure.md b/guides/development/testing/e2e-playwright/install-configure.md
similarity index 100%
rename from guides/plugins/plugins/testing/playwright/install-configure.md
rename to guides/development/testing/e2e-playwright/install-configure.md
diff --git a/guides/plugins/plugins/testing/playwright/language-agnostic-testing.md b/guides/development/testing/e2e-playwright/language-agnostic-testing.md
similarity index 100%
rename from guides/plugins/plugins/testing/playwright/language-agnostic-testing.md
rename to guides/development/testing/e2e-playwright/language-agnostic-testing.md
diff --git a/guides/plugins/plugins/testing/playwright/local-development.md b/guides/development/testing/e2e-playwright/local-development.md
similarity index 100%
rename from guides/plugins/plugins/testing/playwright/local-development.md
rename to guides/development/testing/e2e-playwright/local-development.md
diff --git a/guides/plugins/plugins/testing/playwright/page-object.md b/guides/development/testing/e2e-playwright/page-object.md
similarity index 100%
rename from guides/plugins/plugins/testing/playwright/page-object.md
rename to guides/development/testing/e2e-playwright/page-object.md
diff --git a/guides/plugins/plugins/testing/playwright/test-data-service.md b/guides/development/testing/e2e-playwright/test-data-service.md
similarity index 100%
rename from guides/plugins/plugins/testing/playwright/test-data-service.md
rename to guides/development/testing/e2e-playwright/test-data-service.md
diff --git a/guides/plugins/plugins/testing/playwright/test-suite-types.md b/guides/development/testing/e2e-playwright/test-suite-types.md
similarity index 100%
rename from guides/plugins/plugins/testing/playwright/test-suite-types.md
rename to guides/development/testing/e2e-playwright/test-suite-types.md
diff --git a/guides/plugins/plugins/testing/playwright/test.md b/guides/development/testing/e2e-playwright/test.md
similarity index 100%
rename from guides/plugins/plugins/testing/playwright/test.md
rename to guides/development/testing/e2e-playwright/test.md
diff --git a/guides/development/testing/index.md b/guides/development/testing/index.md
new file mode 100644
index 0000000000..80f1b0ae4e
--- /dev/null
+++ b/guides/development/testing/index.md
@@ -0,0 +1,63 @@
+---
+nav:
+ title: Testing
+ position: 80
+
+---
+
+# Testing
+
+This section covers automated testing strategies and quality requirements for Shopware extensions.
+
+## End-to-End testing
+
+For simulating real user journeys and integration scenarios, Shopware recommends end-to-end (E2E) testing. Playwright is the officially supported tool for automating entire workflows across the application.
+
+Playwright provides:
+
+* Preconfigured fixtures
+* Storefront and Administration page objects
+* API clients
+* Test data helpers
+
+<PageRef page="../testing/e2e-playwright/index" title="E2E playwright" />
+
+## Unit testing
+
+Shopware supports both PHP backend logic and JavaScript components (for Storefront and Administration). Unit tests validate isolated logic in your extension.
+
+### PHP (PHPUnit)
+
+Use PHPUnit to write and run backend unit tests for your PHP code.
+
+<PageRef page="../testing/unit/php-unit" />
+
+### JavaScript (Jest)
+
+Use Jest to test Storefront JS and Vue components following modern best practices.
+
+<PageRef page="../testing/unit/jest-storefront" />
+
+Test custom Administration panel modules and components using Jest with the Shopware admin setup.
+
+<PageRef page="../testing/unit/jest-admin" />
+
+## Continuous Integration (CI)
+
+Automate quality checks, builds, and artifact creation in your CI pipeline to keep extensions reproducible and safe to deploy.
+
+Learn how to structure CI for projects and plugins, including static analysis, test execution, and artifact promotion:
+
+<PageRef page="../testing/ci" />
+
+## Testing guidelines for extensions
+
+To publish your extension in the Shopware Store, follow the testing criteria used during the Store review process.
+
+<PageRef page="../testing/testing-guidelines" />
+
+It focuses on how your extension is functionally tested before approval.
+
+For the official publication requirements, legal conditions, and compliance rules, see:
+
+<PageRef page="../monetization/quality-guidelines" />
diff --git a/guides/plugins/plugins/testing/cypress/cypress-best-practises.md b/guides/development/testing/legacy/cypress/cypress-best-practises.md
similarity index 60%
rename from guides/plugins/plugins/testing/cypress/cypress-best-practises.md
rename to guides/development/testing/legacy/cypress/cypress-best-practises.md
index 6557fc91a0..11d956c913 100644
--- a/guides/plugins/plugins/testing/cypress/cypress-best-practises.md
+++ b/guides/development/testing/legacy/cypress/cypress-best-practises.md
@@ -7,8 +7,6 @@ nav:
# Best practices for writing end-to-end tests
-## Overview
-
A typical E2E test can be complex, with many steps that take a lot of time to complete manually. Because of this complexity, E2E tests can be difficult to automate and slow to execute. The following tips can help reduce the cost and pain of E2E testing and still reap the benefits.
Cypress got you covered with their best practices as well: So please also look at their best practices to get to know their patterns:
@@ -16,14 +14,14 @@ Cypress got you covered with their best practices as well: So please also look a
<PageRef page="https://docs.cypress.io/guides/references/best-practices.html" title="Best Practices | Cypress Documentation" target="_blank" />
::: warning
-We strongly recommend following Cypress own best practices as well.
+We strongly recommend following Cypress's own best practices as well.
:::
## Amount and prioritization of end-to-end tests
### Video
-When it comes to dividing test types, selecting and prioritizing test cases, and thus designing tests, things get a bit more complicated. We have generally aligned our test strategy with the test pyramid, although not 100%. The pyramid states that end-to-end tests should be written in a few but well chosen test cases because end-to-end tests are slow and expensive.
+When it comes to dividing test types, selecting and prioritizing test cases, and thus designing tests, things get a bit more complicated. We have generally aligned our test strategy with the test pyramid, although not 100%. The pyramid states that end-to-end tests should be written in a few but well-chosen test cases because end-to-end tests are slow and expensive.
At [Shopware Community Day](https://scd.shopware.com/en-US/) 2020, we gave a talk on how we approach automated testing in Shopware, how far we have come on this journey, and what we have gained so far:
@@ -41,7 +39,7 @@ Cover every possible workflow with E2E tests.
Use proper prioritization to choose test cases covered by E2E tests.
:::
-Due to running times, it is not advisable to cover every single workflow available. The following criteria may help you with that:
+Due to time constraints, it is not advisable to cover every available workflow. The following criteria may help you with that:
* **Cover the most general, most used workflows of a feature**, e.g., CRUD operations. The term "[happy path](https://en.wikipedia.org/wiki/Happy_path)" describes those workflows quite well.
* **Beware the critical path**: Cover those workflows with E2E tests, which are the most vulnerable and would cause the most damage if broken.
@@ -55,7 +53,7 @@ Write the E2E test as you would write unit tests.
:::
::: tip
-Writing E2E tests in a "workflow-based" manner means writing the test describing a real user's workflow just like a real user would use your application.
+Writing E2E tests in a "workflow-based" manner means writing tests that describe a real user's workflow, just as a real user would use your application.
:::
A test should be written "workflow-based" - We like to use this word very much because it is simply apt for this purpose. You should always keep your persona and goal of an E2E test in mind. The test is then written from the user's point of view, not from the developer's point of view.
@@ -72,72 +70,72 @@ Write long E2E tests covering lots of workflows and use cases.
Keep tests as simple as possible. Only test the workflow you explicitly want to test. Ideally, use **one test for one workflow**.
:::
-The second most important thing is to test the workflow you explicitly want to test. Any other steps or workflows to get your test running should be done using API operations in the `beforeEach` hook, as we don't want to test them more than once. For example, if you want to test the checkout process, you shouldn't do all the steps, like creating the sales channel, products, and categories, although you need them to process the checkout. Use the API to create these things and let the test just do the checkout.
+The second most important thing is to test the workflow you explicitly want to test. Any other steps or workflows to get your test running should be performed via API operations in the `beforeEach` hook, since we don't want to test them more than once. For example, if you want to test the checkout process, you shouldn't do all the steps, like creating the sales channel, products, and categories, although you need them to process the checkout. Use the API to create these things, and let the test just do the checkout.
-You need to focus on the workflow to be tested to ensure minimum test runtimes and to get a valid result of your test case if it fails. For this workflow, you have to think like the end-user would do - Focus on the usage of your feature, not technical implementation.
+You need to focus on the workflow to be tested to ensure minimum test runtimes and to get a valid result of your test case if it fails. For this workflow, you have to think like the end-user would do - Focus on the usage of your feature, not the technical implementation.
-Other examples of steps or workflow to cut off the actual tests are:
+Other examples of steps or workflows to cut off the actual tests are:
-* The routines which should only provide the data we need: Just use test fixtures to create this data to have everything available before the test starts.
+* The routines that should only provide the data we need: Just use test fixtures to create this data to have everything available before the test starts.
* Logging in to the Administration: You need it in almost every Administration test, but writing it in all tests is pure redundancy and way more error sensitive.
::: info
-This [scope practice](https://docs.cypress.io/guides/references/best-practices.html#Organizing-Tests-Logging-In-Controlling-State) is also mentioned in Cypress best practices as well.
+This [scope practice](https://docs.cypress.io/guides/references/best-practices.html#Organizing-Tests-Logging-In-Controlling-State) is also mentioned in the Cypress best practices.
:::
### Focus on stability first
::: danger
-Design your tests dependent on each other, doing lots of write operations without removing corresponding data.
+Design your tests so they depend on each other, performing many write operations without removing the corresponding data.
:::
::: tip
-Keep tests isolated, enable them to run independently, and restore a clean installation between tests
+Keep tests isolated, enable them to run independently, and restore a clean installation between tests.
:::
-It is important to focus on stability as the most important asset of a test suite. A flaky test like this can block the continuous deployment pipeline, making feature delivery slower than it needs to be. Moreover, imagine the following case: Tests that fail to deliver deterministic results: Those flaky test is problematic because they won't show valid results anymore, making them useless. After all, you wouldn't trust one any more than you would trust a liar. If you want to find out more on that topic, including solutions, please take a look at this article:
+It is important to focus on stability as the most important asset of a test suite. A flaky test like this can block the continuous deployment pipeline, making feature delivery slower than it needs to be. Moreover, imagine the following case: Tests that fail to deliver deterministic results. Those flaky tests are problematic because they won't show valid results, making them useless. After all, you wouldn't trust one any more than you would trust a liar. If you want to find out more on that topic, including solutions, please take a look at this article:
<PageRef page="https://www.smashingmagazine.com/2021/04/flaky-tests-living-nightmare/" title="Flaky tests" target="_blank" />
This was one of the reasons you need stable tests to create value. To achieve that, you have several possibilities. We will introduce you to some of them in the following paragraphs.
-Let's start with some easy strategy. Keep tests as simple as possible, and avoid a lot of logic in each one. Think about it this way, the more you do in a test, the more you can go wrong. In addition, by avoiding big tests, you avoid causing load on your application and resource leaks in your environment.
+Let's start with an easy strategy. Keep tests as simple as possible, and avoid a lot of logic in each one. Think about it this way: the more you do in a test, the more you can go wrong. In addition, by avoiding big tests, you avoid causing a load on your application and resource leaks in your environment.
-When planning your test cases and structure, always keep your tests isolated from other tests so that they are able to be run in an independent or random order. Don't ever rely on previous tests. You need to test specs in isolation to take control of your application’s state. Every test is supposed to be able to run on its own and independent from any other tests. This is crucial to ensure valid test results. You can realize these using test fixtures to create all data you need beforehand and take care of the cleanup of your application using an appropriate reset method.
+When planning your test cases and structure, always keep your tests isolated from other tests so they can be run in an independent or random order. Don't ever rely on previous tests. You need to test specs in isolation to take control of your application’s state. Every test is supposed to run independently of any other tests. This is crucial to ensure valid test results. You can realize these using test fixtures to create all the data you need beforehand and take care of the cleanup of your application using an appropriate reset method.
## Choosing selectors
::: danger
-Choose fuzzy selectors which are prone to change, e.g. xpath.
+Choose fuzzy selectors that are prone to change, e.g., XPath.
:::
::: tip
-Use selectors which won't change often.
+Use selectors that won't change often.
:::
-XPath selectors are quite fuzzy and rely a lot on the texts, which can change quickly. Please avoid using them as much as possible. If you work in Shopware platform and notice that one selector is missing or not unique enough, just add another one in the form of an additional class.
+XPath selectors rely heavily on text, which can change quickly. Please avoid using them as much as possible. If you work on the Shopware platform and notice that one selector is missing or not unique enough, just add another one in the form of an additional class.
-### Avoid framework specific selectors
+### Avoid framework-specific selectors
::: danger
-Choose framework specific syntax as a selector prone to change, e.g. `.btn-primary`.
+Choose framework-specific syntax as a selector prone to change, e.g., `.btn-primary`.
:::
::: tip
-Use individual selectors which won't often change, e.g., `.btn-buy`.
+Use individual selectors that won't often change, e.g., `.btn-buy`.
:::
-Using selectors which rely on a framework specific syntax can be unstable because the framework selectors are prone to change. Instead, you should use individual selectors, which are less likely to change.
+Using selectors that rely on a framework-specific syntax can be unstable because the framework selectors are prone to change. Instead, you should use individual selectors, which are less likely to change.
```html
<button class="btn btn-primary btn-buy">Add to cart</button>
```
```javascript
-// ✗ Avoid using framework specific syntax from Bootstrap as a selector.
+// ✗ Avoid using framework-specific syntax from Bootstrap as a selector.
cy.get('.btn.btn-primary').click();
-// ✓ Instead, you should use a shopware specific class like `.btn-buy`.
+// ✓ Instead, you should use a shopware-specific class like `.btn-buy`.
// (This also remains stable when the button variant is changed to, e.g., `.btn-secondary`.)
cy.get('.btn-buy').click();
```
@@ -147,15 +145,15 @@ cy.get('.btn-buy').click();
data-toggle="modal"
data-target="#exampleModal"
class="btn btn-primary btn-open-settings">
- Open settings modal
+ Open settings modal
</button>
```
```javascript
-// ✗ Avoid using framework specific syntax from Bootstrap as a selector.
+// ✗ Avoid using framework-specific syntax from Bootstrap as a selector.
cy.get('[data-toggle="modal"]').click();
-// ✓ Instead, you should use a shopware specific class like `.btn-open-settings`.
+// ✓ Instead, you should use a shopware-specific class like `.btn-open-settings`.
cy.get('.btn-open-settings').click();
```
@@ -164,20 +162,20 @@ cy.get('.btn-open-settings').click();
<label
for="tos"
class="checkout-confirm-tos-label custom-control-label">
- I have read and accepted the general terms and conditions.
+ I have read and accepted the general terms and conditions.
</label>
</div>
```
```javascript
-// ✗ Avoid using framework specific syntax from Bootstrap as a selector.
+// ✗ Avoid using framework-specific syntax from Bootstrap as a selector.
cy.get('.custom-checkbox label').click();
-// ✓ Instead, you should use a shopware specific class like `.checkout-confirm-tos-label`.
+// ✓ Instead, you should use a shopware-specific class like `.checkout-confirm-tos-label`.
cy.get('.checkout-confirm-tos-label').click();
```
-If there are no suitable selectors available, please add descriptive classes or IDs for your desired elements.
+If no suitable selectors are available, please add descriptive classes or IDs to your desired elements.
## Waiting in E2E tests
@@ -189,13 +187,13 @@ Waiting for arbitrary time periods, e.g., using `cy.wait(500)`
Use route aliases or assertions to guard Cypress from proceeding until an explicit condition is met.
:::
-Never use fixed waiting times in the form of `.wait(500)` or similar. Using Cypress, you never need to do this. Cypress has a built-in retry-ability in almost every command, so you don't need to wait, e.g., if an element already exists. If you need more than that, we got you covered. Wait for changes in the UI instead, notifications, API requests, etc., via the appropriate assertions. For example, if you need to wait for an element to be visible:
+Never use fixed waiting times in the form of `.wait(500)` or similar. Using Cypress, you never need to do this. Cypress has a built-in retryability in almost every command, so you don't need to wait, e.g., if an element already exists. If you need more than that, we've got you covered. Wait for changes in the UI instead, notifications, API requests, etc., via the appropriate assertions. For example, if you need to wait for an element to be visible:
```javascript
cy.get('.sw-category-tree').should('be.visible');
```
-Another useful way for waiting in the Administration is using Cypress possibility to work with [network requests](https://docs.cypress.io/app/guides/network-requests). Here you can let the test wait for a successful API response:
+Another useful way to wait in the Administration is to use Cypress's [network requests](https://docs.cypress.io/app/guides/network-requests). Here you can let the test wait for a successful API response:
```javascript
cy.server();
@@ -213,13 +211,13 @@ cy.wait('@getData').then((xhr) => {
```
::: info
-This [best practice](https://docs.cypress.io/guides/references/best-practices#Unnecessary-Waiting) is also mentioned in Cypress best practices as well. Actually, it can be considered a general best practice to avoid flakiness.
+This [best practice](https://docs.cypress.io/guides/references/best-practices#Unnecessary-Waiting) is also mentioned in the Cypress best practices. Actually, avoiding flakiness is a general best practice.
:::
## Cypress commands and their queue
::: danger
-Using vanilla JavaScript logic alongside cypress commands without further caution
+Using vanilla JavaScript logic alongside Cypress commands without further caution
:::
::: tip
@@ -228,7 +226,7 @@ If you need vanilla Javascript in your test, wrap it in a Cypress `then` or buil
Cypress commands are asynchronous and get queued for execution at a later time. During execution, subjects are yielded from one command to the next, and a lot of helpful Cypress code runs between each command to ensure everything is in order.
-This won't happen with Vanilla JS, though. It will be executed immediately. In the worst case, this difference can cause timing issues. So always wrap your vanilla JavaScript code into Cypress commands or `then` in order to make use of Cypress command queue.
+This won't happen with Vanilla JS, though. It will be executed immediately. In the worst case, this difference can cause timing issues. So always wrap your vanilla JavaScript code into Cypress commands or `then` in order to make use of the Cypress command queue.
::: warning
Concerning Cypress `then`: Even though Cypress commands look like promises, they aren't completely the same. Head over to the [Cypress docs](https://docs.cypress.io/guides/core-concepts/introduction-to-cypress#Commands-Are-Not-Promises) for more information.
diff --git a/guides/development/testing/legacy/cypress/index.md b/guides/development/testing/legacy/cypress/index.md
new file mode 100644
index 0000000000..a5ea6c2caf
--- /dev/null
+++ b/guides/development/testing/legacy/cypress/index.md
@@ -0,0 +1,548 @@
+---
+nav:
+ title: Cypress
+ position: 11
+
+---
+
+# Cypress
+
+In end-to-end testing \(E2E testing in short\), real user workflows are simulated, whereby as many as possible functional areas and parts of the technology stack used in the application should be included. This way, we are able to put our UI under constant stress and ensure that Shopware's main functionalities are always working correctly.
+
+## Prerequisites
+
+To run Shopware E2E tests, you first need a Shopware 6 installation running. To ensure your tests are reliable, you should have a clean installation. Cleanup means no categories, no products, no settings, nothing!
+
+The easiest way to clean up your installation is the initialization. Using the command `composer run init`, Shopware 6 gets initialized clean and without demo data. Installation of E2E dependencies can be done separately by running `npm install` in the E2E folder you're using, e.g., for Shopware Administration, it's `src/Administration/Resources/app/administration/test/e2e`.
+
+Since our tests should run on an installation that is as close as possible to a release package, we use production mode. If you run the tests on a development environment, the test results may vary.
+
+Additionally, please make sure your shop has a theme assigned. When using `composer run e2e:open` or `run`, this is done automatically.
+
+This guide also won't teach you how to write Cypress tests in general. Please refer to the official Cypress documentation for further guidance.
+
+<PageRef page="https://docs.cypress.io/" title="Cypress Documentation" target="_blank" />
+
+### Using our testsuite
+
+The [E2E platform testsuite package](https://github.com/shopwareArchive/e2e-testsuite-platform) contains commands and helpers supporting you while building E2E tests for Shopware 6. On top of that, test data management and custom commands are included. More on that here: [Command reference](../../../../../resources/references/core-reference/commands-reference.md).
+
+This test suite is built on top of [Cypress](https://www.cypress.io/) as well as the following Cypress plugins:
+
+* [cypress-select-tests](https://github.com/bahmutov/cypress-select-tests)
+* [cypress-log-to-output](https://github.com/flotwig/cypress-log-to-output)
+* [cypress-file-upload](https://github.com/abramenal/cypress-file-upload)
+
+Here you can find the npm package of our testsuite:
+
+<PageRef page="https://www.npmjs.com/package/@shopware-ag/e2e-testsuite-platform" title="@shopware-ag/e2e-testsuite-platform - npm" target="_blank" />
+
+Please have a look at our [cypress.json](https://github.com/shopwareArchive/e2e-testsuite-platform/blob/3.x/cypress.json). A few of our commands expect configuration, e.g., viewportHeight and width, because the admin menu only opens if the viewport is wide enough.
+
+## Setup steps
+
+When you use our [Development template](https://github.com/shopwareArchive/development), we provide you with some tooling scripts in `dev-ops/e2e/actions` to run E2E tests more comfortably.
+
+The `composer` scripts to run our E2E tests in CLI or in Cypress' test runner are explained in the "Executing E2E Tests" section below.
+
+<Tabs>
+<Tab title="Plugin setup">
+
+Depending on your environment \(administration or storefront\), please create the following folder structure:
+
+```text
+Resources
+ `-- app
+ `-- <environment>
+ `-- test
+ `-- e2e
+ `-- cypress
+ |-- fixtures
+ |-- integration
+ |-- plugins
+ `-- support
+```
+
+We will cover the use of every folder in detail.
+
+Within the folder `Resources/app/<environment>/test/e2e`, please run `npm init -y` to generate a `package.json` file. It is very convenient to place a script inside the newly created `package.json` to run the tests locally. Please add the following section to do so:
+
+```javascript
+"scripts": {
+ "open": "node_modules/.bin/cypress open"
+},
+```
+
+Now install this package with the following command:
+
+```text
+npm install @shopware-ag/e2e-testsuite-platform
+```
+
+As the next step, please create a new file `e2e/cypress/plugins/index.js` with the following content:
+
+```javascript
+module.exports = require('@shopware-ag/e2e-testsuite-platform/cypress/plugins');
+```
+
+Finally, create a new file e2e/cypress/support/index.js with the following line:
+
+```javascript
+// Require test suite commands
+require('@shopware-ag/e2e-testsuite-platform/cypress/support');
+```
+
+</Tab>
+
+<Tab title="Platform: Developing with docker">
+If you are using docker, you don't need to install a thing: We use the [Cypress/Included image](https://github.com/cypress-io/cypress-docker-images/tree/master/included) to use Cypress in Docker completely.
+
+However, since we're using this image to run the test runner as well, you may need to configure it first. Based on this [guide](https://www.cypress.io/blog/run-cypress-with-a-single-docker-command), you need to forward the XVFB messages from Cypress out of the Docker container into an X11 server running on the host machine. The guide shows an example for Mac; other operating systems might require different commands.
+
+In case you're using Docker on Mac, we have summarized the steps from the guide mentioned above, so you can follow these to prepare your environment to get the Test Runner up and running:
+
+**Install and configure XQuartz**
+
+Install XQuartz via [Homebrew](https://docs.brew.sh/Installation) or alternatively [download](https://www.xquartz.org/) it from the official homepage:
+
+```bash
+brew install --cask xquartz
+```
+
+Run XQuartz via CLI or open it from your Desktop:
+
+```bash
+open -a XQuartz
+```
+
+Got to `XQuartz > Preferences` (`⌘ + ,`) and enable `Allow connections from network clients`:
+
+
+
+::: warning
+Restart your Mac before proceeding with the following steps.
+:::
+
+**Configure your environment**
+
+Grab your IP address and save it to the environment variable `IP`:
+
+```bash
+IP=$(ipconfig getifaddr en0)
+```
+
+Depending on how you're connected, you might have to use another interface instead of `en0`.
+
+Now set the `DISPLAY` environment variable:
+
+```bash
+DISPLAY=$IP:0
+```
+
+Add `$IP` to xhost's ACL:
+
+```bash
+xhost + $IP
+```
+
+::: danger
+It is **crucial** to set these environment variables in the **same terminal session** from where you will later run `psh e2e:open`!
+
+Make sure the `DISPLAY` environment variable on your Mac is correctly set **before** you start the containers, as it will be **passed** to the Cypress container when it is **created**.
+Updating the variable on your host won't update it in the container until it is re-created!
+:::
+</Tab>
+</Tabs>
+
+## Executing E2E tests
+
+<Tabs>
+<Tab title="Plugin setup">
+
+If you want to run E2E tests in your plugin, just switch to the folder `Resources/app/<environment>/test/e2e` and execute the following command:
+
+```bash
+CYPRESS_baseUrl=<your-url> npm run open
+```
+
+`<your-url>` means the Storefront URL of your Shopware environment.
+
+It opens the Cypress test runner, which lets you run and debug your tests, similar to the `e2e:open` command.
+
+::: danger
+Don't forget that you might need to adjust test cleanup and other environment-related settings based on your plugin's setup.
+:::
+
+</Tab>
+
+<Tab title="Execution in platform project">
+If you use Docker for your development environment, you can start right away.
+
+To prepare your shopware installation, your environment, and install dependencies, please run the following command as the first step, **outside** of your docker container:
+
+```bash
+ composer run e2e:setup
+```
+
+In our tests, we assume a clean shopware installation, so we strongly recommend using `e2e:setup`. However, if your shopware installation is already clean and prepared, you can skip the preparation of your shopware installation by using the following command **inside** your docker container:
+
+```bash
+ composer run e2e:prepare
+```
+
+Afterwards, just use the following command outside of your container to run the Cypress Test Runner:
+
+```bash
+composer run e2e:open
+```
+
+If you want to run the tests in CLI, please use the following command outside your container:
+
+```bash
+composer e2e:cypress -- run --spec="cypress/e2e/administration/**/*.cy.js"
+```
+
+or
+
+```bash
+composer e2e:cypress -- run --spec="cypress/e2e/storefront/**/*.cy.js"
+```
+
+To see a complete overview of all PSH scripts for e2e tests, feel free to refer to our [e2e command reference](../../../../../resources/references/testing-reference/e2e-commands/).
+</Tab>
+</Tabs>
+
+## Writing your first test
+
+### Folder structure
+
+In the Shopware platform, you can find the tests in `src/Administration/Resources/app/administration/test/e2e`. There you can find the following folder structure, depending on your environment being Administration or Storefront:
+
+```bash
+`-- e2e
+ `-- cypress
+ |-- fixtures
+ `-- example.json
+ |-- integration
+ `-- testfile.spec.js
+ |-- plugins
+ `-- index.js
+ |-- support
+ |-- commands.js
+ `-- index.js
+ |--cypress.json
+ `--cypress.env.json
+```
+
+In the `cypress` folder, all test-related folders are located. Most things will take place in these four folders:
+
+* `fixtures`: Fixtures are used as external pieces of static data that your tests can use. You can use them with the `cy.fixture` command.
+
+* `integration`: By default, the test files are located here. A file with the suffix "\*.spec.js" is a test file that contains a sequence of tests, performed in the order defined in it.
+
+* `plugins`: Contains extensions or plugins. By default, Cypress automatically includes the plugins file before every spec file it runs.
+
+* `support`: The support folder is a great place to put reusable behavior, such as custom commands or global overrides, that you want to be applied and available to all of your spec files.
+
+These two configuration files are essential to mention as well:
+
+* `cypress.json`
+* `cypress.env.json`
+
+ These are Cypress configuration files. If you need more information about them, take a look at the
+
+ [Cypress configuration docs](https://docs.cypress.io/app/references/configuration).
+
+If you need to use this structure in a plugin, it is just the path to the `e2e` folder, which is slightly different. You can find the folder structure in the "Setup Steps" section below.
+
+If you want to contribute to the Shopware platform's tests, please ensure to place your test in one of those folders:
+
+```javascript
+`-- integration
+ |-- catalogue
+ |-- content
+ |-- customer
+ |-- general
+ |-- media-marketing
+ |-- order
+ |-- rule-product-stream
+ `-- settings
+```
+
+::: warning
+This is important because otherwise your test is not considered by our CI.
+:::
+
+### Test layout and syntax
+
+Cypress tests are written in Javascript. If you worked with Mocha before, you will be familiar with Cypress' test layout. The test interface borrowed from Mocha provides `describe()`, `context()`, `it()` and `specify()`.
+
+To have a frame surrounding your test and provide a nice way to keep your test organized, use `describe()` \(or `context()` as its alias\):
+
+```javascript
+describe('Test: This is my test file', () => {
+ it('test something', () => {
+ // This is your first test
+ });
+ it('tests something else', () => {
+ // This is your second test
+ });
+});
+```
+
+The `it()` functions within the `describe()` function are your actual tests. Similar to `describe()` and `context()`, `it()` is identical to `specify()`. However, for writing Shopware tests, we focus on `it()` to keep it consistent.
+
+## Commands and assertions
+
+In Cypress, you use commands and assertions to describe the workflow you want to test.
+
+### Commands
+
+Commands are the actions you need to perform to interact with the elements of your application and reproduce the workflow you intend to test in the end.
+
+```javascript
+it('test something', () => {
+ ...
+ cy.get('.sw-grid__row--0')
+ .contains('A Set Name Snippet')
+ .dblclick();
+ cy.get('.sw-grid__row--0 input')
+ .clear()
+ .type('Nordfriesisch')
+ .click();
+ ...
+ });
+```
+
+You can chain commands by passing their return value to the next one. These commands may include additional steps, e.g., a `click` or `type` operation.
+
+Cypress provides many commands to represent a variety of steps a user could take. On top of that, our E2E testsuite contains a couple of [custom commands](../../../../../resources/references/testing-reference/e2e-custom-commands.md) specially for Shopware.
+
+### Assertions
+
+Assertions describe the desired state of your elements, objects, and application. Cypress bundles the Chai Assertion Library \(including extensions for Sinon and jQuery\) and supports both BDD \(expect/should\) and TDD \(assert\) style assertions. For consistency reasons, we prefer BDD syntax in Shopware's tests.
+
+```javascript
+it('test something', () => {
+ ...
+ cy.get('.sw-loader')
+ .should('not.exist')
+ .should('be.visible')
+ .should('not.have.css', 'display', 'none');
+ cy.get('div')
+ .should(($div) => {
+ expect($div).to.have.length(1)
+ });
+ ...
+ });
+```
+
+## Hooks
+
+You might want to set hooks to run before a set of tests or before each test. At Shopware, we use those, e.g., to clean up Shopware itself, log in to the Administration, or to set the admin language.
+
+Cypress got you covered, similar to Mocha, by providing hooks. These can be used to set conditions that run before or after a set of tests, or before or after each test.
+
+```javascript
+describe('We are using hooks', function() {
+ before(function() {
+ // runs once before all tests in the block
+ })
+
+ beforeEach(function() {
+ // runs before each test in the block
+ })
+
+ afterEach(function() {
+ // runs after each test in the block
+ })
+
+ after(function() {
+ // runs once after all tests in the block
+ })
+})
+```
+
+### Build up and teardown
+
+As we mentioned before, we use these hooks to build up the ideal situation for our test to run. This includes cleaning up the tests' state - based on a clean Shopware installation. According to Cypress's [thoughts on anti-patterns](https://docs.cypress.io/guides/references/best-practices.html#Using-after-or-afterEach-hooks), we clean up the previous state of Shopware beforehand. The reason is pretty simple: You can't be completely sure to reach the `after` hook \(sometimes tests may fail\), the safer way to clean up your tests is the `beforeEach` hook. In addition to stability advantages, it's possible to stop tests at any time without manual cleanup.
+
+## Handling test data
+
+It's important and necessary that the E2E tests are isolated. This means the test should be created beforehand, with all the data needed to run it. Afterwards, the state in the database and the browser must be removed completely. This way, the spec avoids dependencies on demo data or data from other tests, and it cannot be disturbed by them.
+
+One test should only test one workflow, the one it's written for. For example, if you want to test product creation, you should not include category creation in your test, even though it is needed to test the product properly. As best practice, we recommend handling everything not related to the test using the [lifecycle hooks](https://docs.cypress.io/guides/core-concepts/writing-and-organizing-tests.html#Hooks) provided by Cypress.
+
+In the Shopware platform, we use Shopware's REST API to create the data we need. As a result, our tests can focus on a single workflow without testing the workflows that are typically required to provide the data we need. Another aspect of handling it this way is that creating test data via API is faster than doing it inside the test.
+
+### Cypress' fixtures
+
+To define the request you send to Shopware and to set the first test data, store it as a `json` file in the folder `e2e/cypress/fixtures`. You can use those files to provide fixed test data that can be used directly to create the desired entity without any further searching or processing. Fortunately, Cypress provides a way to handle those fixtures by default. The command `cy.fixture()` loads this fixed set of data located in a JSON file.
+
+The example file below defines and creates a customer. So, it provides the data needed to create a customer in Shopware.
+
+```json
+{
+ "customerNumber": "C-1232123",
+ "salutation": "Mr",
+ "firstName": "Pep",
+ "lastName": "Eroni",
+ "email": "test@example.com",
+ "guest": true,
+ "addresses": [
+ {
+ ...
+ }
+ ]
+}
+```
+
+::: warning
+Use only fields that you can access in the UI / Storefront. Keep in mind that all tests in the file may use the fixture. So keep an eye on compatibility.
+:::
+
+A small note on ID usage: Using IDs may be easier for finding elements, but it isn't a proper way for testing in every case - it depends on your application. You need to be 100% sure that the ID is persistent and won't change between builds. Never use IDs here if you cannot be 100% sure they will not change, e.g., in another build.
+
+::: info
+In our Shopware case, IDs on a UUID basis tend to change from one installation to the next, so they are not always suitable to use as selectors in your test.
+:::
+
+### API implementation
+
+Analogous to the Administration itself, the API access for the e2e test uses [axios](https://www.npmjs.com/package/axios), a promise-based HTTP client for the browser and Node.js.
+
+Just as the Administration does, we use services to access Shopware's REST API. Therefore, we use the ApiService to provide the basic methods for accessing the api. Located in `e2e/cypress/support/service/api.service.js`, ApiService is shared between all repositories and acts as a basis for all your next steps of creating fixtures. That implies that the axios implementation of all important api methods can be found there. This service acts as an interface: Next to the basic functions like get, post, etc, the request method is specified here as well as some Shopware-related methods which have to be available in all repositories.
+
+::: info
+Cypress provides its own axios-based way to handle requests in its command `cy.request`. However, Cypress commands are not real promises; see [Commands are not Promises](https://docs.cypress.io/guides/core-concepts/introduction-to-cypress.html#Commands-Are-Not-Promises). As we aim to parallelize the promises to fetch test data, we use our own implementation instead.
+:::
+
+### Services and commands
+
+To apply all test fixture data to our Shopware installation, we use services to send API requests to find, create, or update the data we need. To access these services conveniently, we provide custom commands, which we'll cover a bit later. Let's continue with the general things first.
+
+All fixture services can be found in `cypress/support/service/`:
+
+```bash
+service
+ |-- administration // this folder stores the Administration channel API services
+ `-- <environment>
+ `-- test
+ `-- e2e
+ `-- cypress
+ |-- fixture
+ |-- admin-api.service.js // Provides all methods which communicate with the admin api directly
+ `-- fixture.service.js // Provides all methods for general fixture handling
+ |-- saleschannel // this one stores the sales channel API services
+ `-- api.service.js // axios interface
+```
+
+If you want to use all known services, you can access them using custom commands. These commands can be found in `cypress/support/commands/api-commands.js` for general operation and `cypress/support/commands/fixture-commands.js` specifically for fixture handling.
+
+#### Default fixture command
+
+The stationary fixtures mentioned in the paragraph "Cypress' fixtures" can be sent to Shopware's REST API directly: In most cases, Shopware does not need any additional data, like IDs or other data already stored in Shopware. That means the request can be sent, and the desired entity can be created immediately: You just need to use the `createDefaultFixture(endpoint, options = [])` command, as seen below:
+
+```javascript
+ beforeEach(() => {
+ cy.createDefaultFixture('tax');
+ });
+```
+
+In this example, a tax rate will be created with the data provided based on the `json` file located in the `fixtures` folder. Let's look at the command in detail:
+
+```javascript
+Cypress.Commands.add('createDefaultFixture', (endpoint, data = {}, jsonPath) => {
+ const fixture = new Fixture();
+ let finalRawData = {};
+
+ if (!jsonPath) {
+ jsonPath = endpoint;
+ }
+
+ // Get test data from cy.fixture first
+ return cy.fixture(jsonPath).then((json) => {
+
+ // Merge fixed test data with possible custom one
+ finalRawData = Cypress._.merge(json, data);
+
+ // Create the fixture using the method from the fixture service
+ return fixture.create(endpoint, finalRawData);
+ });
+});
+```
+
+#### Commands of customised services
+
+You will soon notice that some entities need data that has already been created. That means you have to find the specific IDs or use a completely different approach. In this case, your own service has to be created, located in `e2e/cypress/support/service`. Some examples of these services are:
+
+* Customer
+* Sales channel
+* Languages
+* Products
+
+In most cases, the use of these services is similar to that of the basic ones already implemented. There are commands for each of those services provided by our E2E testsuite package. You don't need to define the API endpoint when using those commands. As these services extend `FixturesService`, all its methods can be used in all other services as well.
+
+#### Writing your own customised service
+
+Let's look at the custom service `shipping.fixture.js`. This service is a relatively simple example - It depicts a service in need of some customization for creating a shipping method correctly. With that being said, let's start.
+
+Your `ShippingFixtureService` has to extend the class `AdminFixtureService`. Afterwards, you create a function called `setShippingFixture(userData)` with the parameter `userData` for the data you want to use to create your shipping method. This way, your class should look like this:
+
+```javascript
+const AdminFixtureService = require('../fixture.service.js');
+
+class ShippingFixtureService extends AdminFixtureService {
+ setShippingFixture(userData) {
+ // Here we're going to create our shipping fixture
+ }
+}
+
+module.exports = ShippingFixtureService;
+
+global.ShippingFixtureService = new ShippingFixtureService();
+```
+
+All custom services hold a distinct method for creating fixtures. First, it's important to collect the necessary data via the REST API. This is done by filtering POST requests used in promises. In your `ShippingFixtureService`, you need the ID of the rule you want to use for availability, as well as the ID of the delivery time.
+
+```javascript
+ const findRuleId = () => this.search('rule', {
+ type: 'equals',
+ value: 'Cart >= 0 (Payment)'
+ });
+ const findDeliveryTimeId = () => this.search('delivery-time', {
+ type: 'equals',
+ value: '3-4 weeks'
+});
+```
+
+The responses of these calls are used to provide the missing IDs for your final POST request. At first, we will merge the missing data with the existing data, then create our shipping method:
+
+```javascript
+return Promise.all([
+ findRuleId(),
+ findDeliveryTimeId()
+]).then(([rule, deliveryTime]) => {
+ return this.mergeFixtureWithData(userData, {
+ availabilityRuleId: rule.id,
+ deliveryTimeId: deliveryTime.id
+ });
+}).then((finalShippingData) => {
+ return this.apiClient.post('/shipping-method?_response=true', finalShippingData);
+});
+```
+
+That's it! There you go: You have successfully created a customised service that sets up a shipping method in Shopware. Actually, we use this service in our platform test to create our shipping method as well. You can find the full service [here](https://github.com/shopwareArchive/e2e-testsuite-platform/blob/master/cypress/support/service/administration/fixture/shipping.fixture.js). Look at this example to see the full class.
+
+Below you will find some best practices and tricks we explored to help you with your testing tasks:
+
+* A source of information can be found in the FieldCollection of several EntityDefinition files. All fields belonging to an entity are defined there. For example, if you're searching for customer-related data, please search for the `CustomerDefinition` in the Shopware platform.
+* If you want to extract mandatory data that is not covered by the error message received with the API's response, it's useful to reproduce your workflow manually: E.g., if you need to find out what data is mandatory for creating a customer, try to save an empty one in the Administration. Keep an eye on your browser's developer tools while doing so, especially in the preview and response sections of your request. As you get your response, you can see what data is still missing.
+* If you need to set non-mandatory data, reproducing the above mentioned workflow is recommended as well: Even if the error response does not contain a readable error, you can still inspect it: All the relevant information is stored in 'data'. IDs can be found there directly; other relevant data is stored in the "attributes" section.
+* Cypress's test runner can help you a lot with inspecting API requests. Just click on the request in the test runner's log to get a full print of it in your console.
+
+## More interesting topics
+
+* [Unit testing with PHPUnit](../../unit/php-unit.md)
+* [Jest unit tests in Shopware's administration](../../unit/jest-admin.md)
+* [Jest unit tests in Shopware's storefront](../../unit/jest-storefront.md)
diff --git a/guides/development/testing/legacy/index.md b/guides/development/testing/legacy/index.md
new file mode 100644
index 0000000000..26e00fa81a
--- /dev/null
+++ b/guides/development/testing/legacy/index.md
@@ -0,0 +1,12 @@
+---
+nav:
+ title: Legacy
+ position: 10
+
+---
+
+# Legacy
+
+:::warning
+Cypress has been deprecated and is no longer maintained. We recommend using [Playwright](../e2e-playwright/index.md) for new projects.
+:::
diff --git a/resources/guidelines/testing/store/index.md b/guides/development/testing/testing-guidelines.md
similarity index 52%
rename from resources/guidelines/testing/store/index.md
rename to guides/development/testing/testing-guidelines.md
index 7304c63b84..901b4c9cf6 100644
--- a/resources/guidelines/testing/store/index.md
+++ b/guides/development/testing/testing-guidelines.md
@@ -7,7 +7,7 @@ nav:
# Testing Guidelines for Shopware Extensions
-This section guides you with the criteria used to test your extension. Detailed information is available on [quality guidelines for apps](../store/quality-guidelines-apps/) and [quality guidelines for plugins](../store/quality-guidelines-plugins/)
+This section guides you with the criteria used to test your extension. Detailed information is available on [quality guidelines for extensions](../monetization/quality-guidelines.md) guide.
Check out the points that affect your extension and go through them before submitting it for testing.
@@ -29,34 +29,34 @@ Not necessary: This point does not need to be tested
Here is what the test criteria include:
-* **[Function availability](../store/quality-guidelines-apps/#every-app-based-on-the-app-system)** - Here, we proceed like a user and check the complete functionality of the app, as well as the logical structure and usability. For instance,
+* **[Function availability](../monetization/quality-guidelines.md#functional-requirements)** - Here, we proceed like a user and check the complete functionality of the app, as well as the logical structure and usability. For instance,
* Is a general function as described in your extension available?
* Do the buttons, export, rules, etc., work?
* Are errors displayed in the console?
-* **[Lighthouse audit home/listing/detail](../store/quality-guidelines-apps/#frontend-apps)** - We check:
+* **[Lighthouse audit home/listing/detail](../monetization/quality-guidelines.md#lighthouse-ab-testing)** - We check:
* If your extension affects the Storefront or not? (so that the search engines have no problems with it).
* If all buttons, labels, etc., are named correctly?
We pay attention to all five audits. The app must not limit these. Like most search engines, we also pay attention to mobile-first.
-* **[Rich snippet home/listing/detail](../store/quality-guidelines-apps/#template-tests)** - We check:
+* **[Rich snippet home/listing/detail](../monetization/quality-guidelines.md#schemaorgrich-snippets-ab-testing-checklist)** - We check:
* If the page can be indexed?
* Is there any incorrect price information being displayed?
Rich snippets have no influence on the ranking of a website. Thus, they do not count among the ranking factors. Nevertheless, search hits enriched with additional information have various SEO advantages: higher attention, higher click-through rate, and greater relevance.
-* **[No errors in the Storefront and 503/404 errors](../store/quality-guidelines-apps/#error-messages-must-be-entered-in-the-event-log)** - We check:
+* **[No errors in the Storefront and 503/404 errors](../monetization/quality-guidelines.md#storefront-guidelines)** - We check:
* If the app is active in the Storefront?
* If it involves display errors and errors of any kind?
The end customer should not receive any misleading error messages. It does not matter whether a function causes the error or the customer does not use the function correctly. For example, the customer can upload a picture using a function, but if the customer tries to upload a video, a clear message should be displayed here.
-* **[Cookie check storefront/checkout](../store/quality-guidelines-apps/#register-a-cookie-to-the-cookie-consent-manager)** - Since the GDPR/DSGVO, the classification of cookies is particularly important. We distinguish between three types of cookies.
+* **[Cookie check storefront/checkout](../monetization/quality-guidelines.md#functional-requirements)** - Since the GDPR/DSGVO, the classification of cookies is particularly important. We distinguish between three types of cookies.
* **Technically required**: Only cookies that are really important for the store without which no purchase would be possible.
@@ -64,15 +64,15 @@ The end customer should not receive any misleading error messages. It does not m
* **Statistics and Tracking**: Statistics and everything that has to do with data collection and tracking.
-* **[Store description German/English](../store/quality-guidelines-apps/#app-descriptions-in-your-shopware-account)** - The app store description includes several points if the app can be used only in a specific country, so leave this clearly in the description. The German description is only mandatory if the app is to be offered in the German market. Furthermore, there must always be at least two images of the app in English, e.g., of the Storefront and the Admin. [Here](https://docs.shopware.com/en/account-en/adding-pictures-and-icons/how-to) you can find a guide detailing how to add images and icons to the extensions.
+* **[Store description German/English](../monetization/quality-guidelines.md#store-listing-requirements)** - The app store description includes several points if the app can be used only in a specific country, so leave this clearly in the description. The German description is only mandatory if the app is to be offered in the German market. Furthermore, there must always be at least two images of the app in English, e.g., of the Storefront and the Admin. [Here](https://docs.shopware.com/en/account-en/adding-pictures-and-icons/how-to) you can find a guide detailing how to add images and icons to the extensions.
-* **[Translations managed admin](../store/quality-guidelines-apps/#fallback-language)** - We check if the app is available in all languages specified in your account. However, it is important that English is fallback if the app does not support any other language.
+* **[Translations managed admin](../monetization/quality-guidelines.md#fallback-languagetranslations)** - We check if the app is available in all languages specified in your account. However, it is important that English is fallback if the app does not support any other language.
-* **[API validation](../store/quality-guidelines-apps/#api-or-payment-apps)** - If access data is required for the app - for example, an API key; a button must be implemented with which the customer can check the data if this is technically possible.
+* **[API validation](../monetization/quality-guidelines.md#app-specific-requirements)** - If access data is required for the app - for example, an API key; a button must be implemented with which the customer can check the data if this is technically possible.
-
+
-* **[Uninstallation process](../store/quality-guidelines-apps/#extension-manager)** - During the uninstallation process, the app should be able to uninstall and install without any problems. It is also important to check whether the app depends on other apps and whether they must be uninstalled first.
+* **[Uninstallation process](../monetization/quality-guidelines.md#functional-requirements)** - During the uninstallation process, the app should be able to uninstall and install without any problems. It is also important to check whether the app depends on other apps and whether they must be uninstalled first.
* **Data will be removed from the database after uninstallation** - If the customer selects the option "delete all data" during uninstallation, then all the data has to be removed from the database that was created with the app.
diff --git a/guides/development/testing/unit/index.md b/guides/development/testing/unit/index.md
new file mode 100644
index 0000000000..c8dee6b313
--- /dev/null
+++ b/guides/development/testing/unit/index.md
@@ -0,0 +1,18 @@
+---
+nav:
+ title: Unit Testing
+ position: 60
+---
+
+# Unit Testing
+
+This section explains how to write and execute unit tests in Shopware.
+
+## JavaScript testing (Jest)
+
+* [Jest unit tests in Shopware's Administration](./jest-admin.md)
+* [Jest unit tests in Shopware's Storefront](./jest-storefront.md)
+
+## PHP testing (PHPUnit)
+
+* [PHP unit testing](./php-unit.md)
diff --git a/guides/plugins/plugins/testing/jest-admin.md b/guides/development/testing/unit/jest-admin.md
similarity index 64%
rename from guides/plugins/plugins/testing/jest-admin.md
rename to guides/development/testing/unit/jest-admin.md
index d4e786b5cf..6125244e5e 100644
--- a/guides/plugins/plugins/testing/jest-admin.md
+++ b/guides/development/testing/unit/jest-admin.md
@@ -7,36 +7,32 @@ nav:
# Jest Unit Tests in Shopware's Administration
-## Overview
-
You should write a unit test for every functional change. It should guarantee that your written code works and that a third developer can't break the functionality with their code.
-With a good test coverage we can have the confidence to deploy a stable software without needing to manually test the software in its entirety. This little guide will guide you how to write unit tests for the Administration in Shopware 6.
+With a good test coverage we can have the confidence to deploy a stable software without needing to manually test the software in its entirety. This little guide will guide you on how to write unit tests for the Administration in Shopware 6.
-We are using [Jest](https://jestjs.io) as our testing framework. It's a solid foundation and widely used by many developers. Before you are reading this guide you have to make sure you understand the basics of unit tests and how Jest works.
+We are using [Jest](https://jestjs.io) as our testing framework. It's a solid foundation and widely used by many developers. Before you read this guide, make sure you understand the basics of unit tests and how Jest works.
## Video
-Did you know that there's a video available to this topic? Please take a look:
-
<YoutubeRef video="nWUBK3fjwVg" title="Writing unit tests with Jest (Developer Tutorial) - YouTube" target="_blank" />
## Prerequisites
-This tutorial will have a strong focus on how unit tests should be written when it comes to components in the Administration. So please make sure you already know what a unit test is and why we are doing it. Furthermore, you should know what components tests are and what we want to achieve with them. You can find a good source for best practices in this Github repository:
+This tutorial will focus heavily on how unit tests should be written for components in the Administration. So please make sure you already know what a unit test is and why we are doing it. Furthermore, you should understand what component tests are and what we aim to achieve with them. You can find a good source for best practices in this GitHub repository:
<PageRef page="https://github.com/goldbergyoni/javascript-testing-best-practices" title="Javascript testing - best practices @ GitHub" target="_blank" />
-In addition, you need a running Shopware 6 installation. Your repository used for that should be based on development template, as we need to use some scripts provided by it.
+In addition, you need a running Shopware 6 installation. Your repository used for that should be based on the development template, as we need to use some scripts provided by it.
## Test file location
-The test files are placed in the same directory as the file which should be tested.
+The test files are placed in the same directory as the file that should be tested.
The file name is the same with the suffix `.spec.js` or `spec.ts`.
## Testing services and ES modules
-Services and isolated ECMAScript modules are well testable because you can import them directly without mocking or stubbing dependencies. A service can be used isolated and therefore is easy to test.
+Services and isolated ECMAScript modules are well testable because you can import them directly without mocking or stubbing dependencies. A service can be used in isolation, making it easy to test.
Let's have a look at an example:
@@ -47,69 +43,69 @@ import Sanitizer from 'src/core/helper/sanitizer.helper';
describe('core/helper/sanitizer.helper.js', () => {
it('should sanitize the html', () => {
expect(Sanitizer.sanitize('<A/hREf="j%0aavas%09cript%0a:%09con%0afirm%0d``">z'))
- .toBe('<a href="j%0aavas%09cript%0a:%09con%0afirm%0d``">z</a>');
- });
+ .toBe('<a href="j%0aavas%09cript%0a:%09con%0afirm%0d``">z</a>');
+ });
it('should remove script functions from dom elements', () => {
expect(Sanitizer.sanitize('<details open ontoggle=confirm()>'))
- .toBe('<details open=""></details>');
- });
+ .toBe('<details open=""></details>');
+ });
it('should remove script functions completely', () => {
expect(Sanitizer.sanitize(`<script y="><">/*<script* */prompt()</script`))
- .toBe('');
- });
+ .toBe('');
+ });
it('should sanitize js in links', () => {
expect(Sanitizer.sanitize('<a href=javascript:alert(1)>click'))
- .toBe('<a>click</a>');
- });
+ .toBe('<a>click</a>');
+ });
// ...more tests
});
```
-You see, you are able to write the test the same way you're used to, writing Jest unit tests in general.
+You see, you can write the test the same way you're used to, writing Jest unit tests in general.
## Write tests for components
-After setting up your component test, you need to write your tests. A good way to write them is to test input and output. The most common tests are:
+After setting up your component test, write your tests. A good way to write them is to test input and output. The most common tests are:
-* set Vue Props and check if component looks correctly
-* interact with the DOM and check if the desired behaviour is happening
+* Set Vue Props and check if the component looks correct
+* Interact with the DOM and check if the desired behaviour is happening
-However, when it comes to writing component tests for Shopware's Administration, there are some further steps to go. We will take a look at them in the following paragraphs.
+However, when it comes to writing component tests for Shopware's Administration, there are some further steps to take. We will take a look at them in the following paragraphs.
## Setup for testing Vue components
-We are using the [Vue Test Utils](https://v1.test-utils.vuejs.org/) for easier testing of Vue components. If you don't have experience with testing Vue components it is useful to read some basic guides on this topic. The main part of testing components is similar in Shopware 6.
+We are using [Vue Test Utils](https://v1.test-utils.vuejs.org/) to make testing Vue components easier. If you don't have experience with testing Vue components, it is useful to read some basic guides on this topic. The central part of testing components is similar in Shopware 6.
-However, there are some important differences. We can't test components that easily like in other Vue projects because we are supporting template inheritance and extendability for third party developers. This causes overhead which we need to bear in mind.
+However, there are some important differences. We can't test components as easily as in other Vue projects because we support template inheritance and extendability for third-party developers. This causes overhead, which we need to bear in mind.
-We are using a global object as an interface for the whole Administration. Every component gets registered to this object, e.g. `Shopware.Component.register()`. Therefore, we have access to Component with the `Shopware.Component.build()` method. This creates a native Vue component with a working template. Every override and extension from another components are resolved in the built component.
+We are using a global object as an interface for the whole Administration. Every component gets registered to this object, e.g., `Shopware.Component.register()`. Therefore, we can access the Component using the `Shopware.Component.build()` method. This creates a native Vue component with a working template. Every override and extension from other components is resolved in the built component.
-## Setup tests with create test command
+## Setup tests with the create test command
You can generate a test boilerplate using the create test command.
-You encountered an untested component or service? Copy the path in your IDE and go to your terminal.
-In the Shopware root directory run `composer run admin:create:test`. Once prompted paste the path you copied and hit enter.
+Did you encounter an untested component or service? Copy the path in your IDE, then open your terminal.
+In the Shopware root directory, run `composer run admin:create:test`. Once prompted, paste the path you copied and hit enter.
-If everything is correct you should now have a `.spec` file with our newest recommended boilerplate code.
+If everything is correct, you should now have a `.spec` file with our newest recommended boilerplate code.
### Executing tests
-Before you are using the commands make sure that you installed all dependencies for your Administration. If you haven't done this already, then you can do it running the following PSH command: `composer run init:js`
+Before you use the commands, make sure you have installed all dependencies for your Administration. If you haven't done this already, then you can do it by running the following PSH command: `composer run init:js`
-In order to run jest unit tests of the Administration, you can use the psh commands provided by our development template.
+To run Jest unit tests of the Administration, you can use the PSH commands provided by our development template.
::: info
-This only applies to the Shopware provided Administration! If you use unit tests in your plugin, you might need to write your own scripts for that.
+This only applies to the Shopware-provided Administration! If you use unit tests in your plugin, you might need to write your own scripts for that.
:::
-This command executes all unit tests and shows you the complete code coverage.
+This command runs all unit tests and displays complete code coverage.
`composer run admin:unit`
-This command executes only unit tests of changed files. It automatically restarts if a file gets saved. This should be used during the development of unit tests.
+This command executes only the unit tests of changed files. It automatically restarts if a file gets saved. This should be used during unit test development.
`composer run admin:unit:watch`
### Example test structure
@@ -131,15 +127,15 @@ async function createWrapper(/* options = {} */): Wrapper {
stubs: {
'sw-missing-component-one': Shopware.Component.build('sw-missing-component-one'),
'sw-missing-component-two': Shopware.Component.build('sw-missing-component-two'),
- },
+ },
mocks: {
// add mocks if needed
- },
+ },
// needed if you interact with elements
attachTo: document.body,
// ...options,
- });
+ });
}
describe('the/path/to/the/component', () => {
@@ -147,15 +143,15 @@ describe('the/path/to/the/component', () => {
beforeAll(async () => {
// generate all needed mocks, etc.
- })
+ })
beforeEach(async () => {
// reset all mocks and state changes to default
wrapper = await createWrapper();
- // wait for created hook etc.
+ // wait for created hook, etc.
await flushPromises();
- })
+ })
afterEach(async () => {
// cleanup everything
@@ -163,15 +159,15 @@ describe('the/path/to/the/component', () => {
// destroy the existing wrapper
if (wrapper) {
await wrapper.destroy();
- }
+ }
// wait until all promises are finished
await flushPromises();
- })
+ })
it('should be a Vue.js component', () => {
expect(wrapper.vm).toBeTruthy();
- });
+ });
// Add more component tests
})
@@ -179,16 +175,16 @@ describe('the/path/to/the/component', () => {
## First example: Testing sw-multi-select component
-For better understanding how to write component tests for Shopware 6 let's write a test. In our example we are using the component `sw-multi-select`.
+To better understand how to write component tests for Shopware 6, let's write a test. In our example, we are using the component `sw-multi-select`.
-When you want to mount your component it needs to be imported first:
+When you want to mount your component, it needs to be imported first:
```javascript
// test/app/component/form/select/base/sw-multi-select.spec.js
import 'src/app/component/form/select/base/sw-multi-select';
```
-You see that we import the `sw-multi-select` without saving the return value. This blackbox import only executes code. However, this is important because this registers the component to the Shopware object:
+You see that we import the `sw-multi-select` without saving the return value. This blackbox import only executes code. However, this is important because it registers the component to the Shopware object:
```javascript
// src/app/component/form/select/base/sw-multi-select/index.js
@@ -199,7 +195,7 @@ Shopware.Component.register('sw-multi-select', {
### Mounting components
-In the next step we can mount our Vue component which we get from the global Shopware object:
+In the next step, we can mount our Vue component, which we get from the global Shopware object:
```javascript
// test/app/component/form/select/base/sw-multi-select.spec.js
@@ -208,12 +204,12 @@ import 'src/app/component/form/select/base/sw-multi-select';
shallowMount(Shopware.Component.build('sw-multi-select'));
```
-When we’re testing our vue.js components, we need a way to mount and render the component. Therefore, we use the following methods:
+When we’re testing our Vue.js components, we need a way to mount and render the component. Therefore, we use the following methods:
* `mount()`: Creates a Wrapper that contains the mounted and rendered Vue component.
* `shallowMount()`: Like mount, it creates a Wrapper that contains the mounted and rendered Vue component,
- but with stubbed child components.
+ but with stubbed child components.
This way, we create a new `wrapper` before each test. The `build` method resolves the twig template and returns a vue component.
@@ -231,19 +227,19 @@ describe('components/sw-multi-select', () => {
beforeEach(() => {
wrapper = shallowMount(Shopware.Component.build('sw-multi-select'));
- });
+ });
afterEach(() => {
wrapper.destroy();
- });
+ });
it('should be a Vue.js component', () => {
expect(wrapper.vm).toBeTruthy();
- });
+ });
});
```
-This contains our component. In our first test we only check if the wrapper is a Vue instance.
+This contains our component. In our first test, we only check if the wrapper is a Vue instance.
### Running the test
@@ -260,11 +256,11 @@ wrapper = shallowMount(Shopware.Component.build('sw-multi-select'), {
props: {
options: [],
value: ''
- }
+ }
});
```
-Now you should only see the last warning with an unknown custom element. The reason for this is that most components contain other components. In our case the `sw-multi-select` needs the `sw-select-base` component. Now we have several solutions to solve this. The two most common ways are stubbing or using the component.
+Now you should only see the last warning with an unknown custom element. The reason for this is that most components contain other components. In our case, the `sw-multi-select` needs the `sw-select-base` component. Now we have several solutions to solve this. The two most common ways are stubbing or using the component.
```javascript
// test/app/component/form/select/base/sw-multi-select.spec.js
@@ -274,14 +270,14 @@ wrapper = shallowMount(Shopware.Component.build('sw-multi-select'), {
props: {
options: [],
value: ''
- },
+ },
stubs: {
'sw-select-base': Shopware.Component.build('sw-select-base'),
- }
+ }
});
```
-You need to choose which way is needed: Many tests do not need the real component, but in our case we need the real implementation. You will see that if we import another component that they can create also warnings. Let's look at the code that solve all warnings, then we should have a code like this:
+You need to choose which approach is needed: many tests do not need the fundamental component, but in our case, we do. You will see that if we import another component, it can also create warnings. Let's look at the code that solves all warnings, then we should have a code like this:
```javascript
// test/app/component/form/select/base/sw-multi-select.spec.js
@@ -307,7 +303,7 @@ describe('components/sw-multi-select', () => {
props: {
options: [],
value: ''
- },
+ },
stubs: {
'sw-select-base': Shopware.Component.build('sw-select-base'),
'sw-block-field': Shopware.Component.build('sw-block-field'),
@@ -321,23 +317,23 @@ describe('components/sw-multi-select', () => {
'sw-highlight-text': Shopware.Component.build('sw-highlight-text'),
'sw-label': Shopware.Component.build('sw-label'),
'sw-button': Shopware.Component.build('sw-button')
- }
- });
- });
+ }
+ });
+ });
afterEach(() => {
wrapper.destroy();
- });
+ });
it('should be a Vue.js component', () => {
expect(wrapper.vm).toBeTruthy();
- });
+ });
});
```
## Second example: Testing of message inside the sw-alert component
-Of course, the complexity and structure of your test depends on what you are trying to achieve with your component. Here is one little example concerning the component `sw-alert`: Actually, he task of an alert is displaying a message for the user in most cases. So in this example, let's write a test for this text located in a slot. You can find this example in the linked video above as well.
+Of course, the complexity and structure of your test depend on what you are trying to achieve with your component. Here is one little example concerning the component `sw-alert`: Actually, the task of an alert is to display a message to the user in most cases. So, in this example, let's write a test for the text in a slot. You can find this example in the linked video above as well.
We will start with an already written test similar to the first example:
@@ -349,15 +345,15 @@ describe('components/base/sw-alert', () => {
it('should be a Vue.js component', () => {
const wrapper = shallowMount(Shopware.Component.build('sw-alert'), {
stubs: ['sw-icon']
- });
+ });
// Assert if our component is a vue instance = mountes correctly
expect(wrapper.vm).toBeTruthy();
- });
+ });
});
```
-There we'll add another test case for testing the alert's message:
+There, we'll add another test case for testing the alert's message:
```javascript
import { shallowMount } from '@vue/test-utils';
@@ -366,11 +362,11 @@ import 'src/app/component/base/sw-alert';
describe('components/base/sw-alert', () => {
it('should be a Vue.js component', () => {
// see above
- });
+ });
it('should render the message inside the default slot', () => {
// New
- });
+ });
});
```
@@ -383,34 +379,34 @@ You can set the content of a slot during component mount. See the paragraph "Mou
const wrapper = shallowMount(Shopware.Component.build('sw-alert'), {
slots: {
default: 'My custom message'
- }
- });
- });
+ }
+ });
+ });
```
-Afterwards you can make an assertion that the text passed to the slot will be rendered inside the desired element. In this case we search in the wrapper for the element with the selector `.sw-alert__message` and check if the text is there:
+Afterwards, you can assert that the text passed to the slot will be rendered inside the desired element. In this case we search in the wrapper for the element with the selector `.sw-alert__message` and check if the text is there:
```javascript
it('should render the message inside the default slot', () => {
const wrapper = shallowMount(Shopware.Component.build('sw-alert'), {
slots: {
default: 'My custom message'
- }
- });
+ }
+ });
expect(wrapper.find('.sw-alert__message').text()).toBe('My custom message');
- });
+ });
```
## Stubbing your component
Vue Test Utils has some advanced features for stubbing components. A stub is actually when you replace an existing implementation of a custom component with a dummy component doing nothing at all, actually. This is necessary for the component to function independently, in an isolated way.
-Components in Shopware might also depend on other dependencies like `$tc`, directives or injections. This way, the setup of your test may get more complex. When you are building components then you need to mock their dependencies as well.
+Components in Shopware might also depend on other dependencies, such as `$tc`, directives, or injections. This way, the setup of your test may get more complex. When you are building components, you need to mock their dependencies as well.
-To improve the test writing experience we included many mocks, helper methods and even more by default. This will help you to reduce the overhead of setting up a single test with all mocks.
+To improve the test-writing experience, we included many mocks, helper methods, and even more by default. This will help you reduce the overhead of setting up a single test with all mocks.
::: info
-Everything can be overwritten in the `mount` or `shallowMount` method if you need to have custom implementation.
+Everything can be overwritten in the `mount` or `shallowMount` method if you need to have a custom implementation.
:::
## Using preconfigured mocks
@@ -433,7 +429,7 @@ it('should render with ACL rights', async () => {
### Feature flags
-If you want to enable feature flags you can add the flag to the global variable `global.activeFeatureFlags`. If you want to, you can change the usage of feature flags for each test.
+If you want to enable feature flags, you can add the flag to the global variable `global.activeFeatureFlags`. If you want to, you can change the usage of feature flags for each test.
Example:
@@ -449,9 +445,9 @@ it('should render with active feature flag', async () => {
### Repository factory
-The data handling and the repository factory works by default. It will be generated by the entity-schema which will be written to a file before you start the test suite.
+Data handling and the repository factory work by default. It will be generated by the entity-schema and written to a file before you start the test suite.
-Every time the repository factory requests something from a URL, you get a notification in the console. This notification also includes a short guide on how to implement the response. This information may look like this:
+Every time the repository factory requests a resource from a URL, you get a console notification. This notification also includes a short guide on how to implement the response. This information may look like this:
```javascript
// You should implement mock data for this route: "/search/product".
@@ -468,14 +464,14 @@ responses.addResponse({
status: 200,
response: {
data: [
- {
+ {
id: YourId,
attributes: {
id: YourId
- }
- }
- ]
- }
+ }
+ }
+ ]
+ }
});
/*
@@ -489,7 +485,7 @@ global.repositoryFactoryMock.showWarning = false;
The response value should contain your test data. It needs to match the response from the backend API. An easy way to get the correct response is to inspect the response from the real API when you open the Administration.
-If you don't want to use this helper then you can easily overwrite it by setting a custom mock for the repositoryFactory in your mount method.
+If you don't want to use this helper, then you can easily overwrite it by setting a custom mock for the repositoryFactory in your mount method.
### Directives
@@ -509,31 +505,31 @@ The global `Shopware` context is prepared automatically. You can overwrite them
### Global mocks
-For most cases we created automatic mocks, so you don´t need to implement them manually. Some examples are `$tc`, `$device`, `$store` or `$router`.
+In most cases, we created automatic mocks, so you don´t need to implement them manually. Some examples are `$tc`, `$device`, `$store`, or `$router`.
-If you want to override one mock then you can do it in the `mount` method:
+If you want to override one mock, then you can do it in the `mount` method:
```javascript
mount('dummy-component', {
mocks: {
$tc: (...args) => JSON.stringify([...args])
- }
+ }
})
```
### Using mocks
-A common warning can occur if you didn't mock functions needed in your component. For example, please look at the warning below:
+A common warning can occur if you didn't mock the functions your component needs. For example, please look at the warning below:
> \[Vue warn\]: Error in render: "TypeError: hasError is not a function"
-The solution is using mocks while mounting your component. In this case, your mock here is a simple function returning the value "true".
+The solution is to use mocks while mounting your component. In this case, your mock is a simple function that returns the value "true".
```javascript
shallowMount(Shopware.Component.build('your-component'), {
mocks: {
hasError: () => false // your mock (here a simple function returning the value "true")
- }
+ }
});
```
@@ -543,7 +539,7 @@ When working with components of Shopware's Administration, you might stumble upo
> \[Vue warn\]: Failed to resolve directive: clipboard
-If that happens, you need to use [localVue](https://v1.test-utils.vuejs.org/api/#createlocalvue) to provide the directive mock. `createLocalVue` returns a Vue class for you to add components, mixins and install plugins without polluting the global Vue class. In our context, it looks like this:
+If that happens, you need to use [localVue](https://v1.test-utils.vuejs.org/api/#createlocalvue) to provide the directive mock. `createLocalVue` returns a Vue class for you to add components, mixins, and install plugins without polluting the global Vue class. In our context, it looks like this:
```javascript
import { shallowMount, createLocalVue } from '@vue/test-utils';
@@ -562,7 +558,7 @@ Another common warning is the one below:
> \[Vue warn\]: Injection "mediaService" not found
-The solution is stubbing this injection. In detail, you need to provide the injected data, services and so on: That means you need to mock the return values for your test's methods used, e.g. `renameMedia` and `uploadMediaById` - Providing the data exactly as needed by the component for running your test case and what the injection actually is. It can be valid to set the injection name equal to an empty object just to mute it when it's not really needed for your test.
+The solution is stubbing this injection. In detail, you need to provide the injected data, services, and so on: That means you need to mock the return values for your test methods used, e.g., `renameMedia` and `uploadMediaById` - Providing the data exactly as needed by the component for running your test case, and what the injection actually is. It's valid to set the injection name to an empty object to mute it when it's not really needed for your test.
```javascript
provide: {
@@ -570,7 +566,7 @@ provide: {
}
```
-Please note that the mediaService has a `renameMedia` method. So in order to stub the `mediaService` in realistic manner, follow the example below:
+Please note that the mediaService has a `renameMedia` method. So to stub the `mediaService` in a realistic manner, follow the example below:
```javascript
mediaService: {
@@ -578,32 +574,26 @@ mediaService: {
}
```
-In the context of injections, the next warning can occur sometimes:
+In the context of injections, the following warning can sometimes occur:
> \[Vue warn\]: Error in foo: "TypeError: Cannot read property 'renameMedia' of undefined"
-This can be caused by several reasons. The best way to find out the solution is to look at the source of the code and find out what is missing. This is highly dependent on the component under test, though. In this example the service `mediaService` is missing:
+This can be caused by several reasons. The best way to find a solution is to look at the source code and identify what is missing. This is highly dependent on the component under test, though. In this example, the service `mediaService` is missing:
```javascript
Shopware.Service('mediaService').renameMedia(mediaId, newFileName);
```
-To fix this you need to add the mocked service before all tests. In our case we need to register the service:
+To fix this, add the mocked service before all tests. In our case, we need to register the service:
```javascript
beforeAll(() => {
Shopware.Service.register('mediaService', {
// your service mock
- });
+ });
});
```
## Next steps
-Do you want to see these examples in practice? Head over to our [video tutorial](https://youtu.be/nWUBK3fjwVg) on how to write component tests in jest for the Shopware Administration.
-
-Furthermore, you might want to have a look at one of the following guides as well:
-
-* [Jest tests for the storefront](jest-storefront/)
-* [PHPUnit tests](php-unit/)
-* [End-to-end tests](end-to-end-testing/)
+Do you want to see these examples in practice? Head over to our [video tutorial](https://youtu.be/nWUBK3fjwVg) on how to write component tests in Jest for the Shopware Administration.
diff --git a/guides/plugins/plugins/testing/jest-storefront.md b/guides/development/testing/unit/jest-storefront.md
similarity index 58%
rename from guides/plugins/plugins/testing/jest-storefront.md
rename to guides/development/testing/unit/jest-storefront.md
index 44bb9e4c90..ef04b67296 100644
--- a/guides/plugins/plugins/testing/jest-storefront.md
+++ b/guides/development/testing/unit/jest-storefront.md
@@ -7,57 +7,55 @@ nav:
# Jest Unit Tests in Shopware's Storefront
-## Overview
+You should write a unit test for every functional change. Writing tests will ensure that your code works and that another change can't break its functionality when their code changes.
-You should write a unit test for every functional change. Writing tests will ensure that your written code works and that another change can't break your code's functionality with their code.
-
-With a good test coverage you gain confidence to deploy a stable software without the requirement to manually test every change. This little guide will guide you how to write unit tests for the Administration in Shopware 6.
+With good test coverage, you gain the confidence to deploy stable software without manually testing every change. This little guide will guide you on how to write unit tests for the Administration in Shopware 6.
We are using JestJS as our testing framework as it's a solid foundation and widely used by many developers.
-<PageRef page="https://jestjs.io" title="Jest · 🃏 Delightful JavaScript Testing" target="_blank" />
+<PageRef page="https://jestjs.io" title="Jest Delightful JavaScript Testing" target="_blank" />
## Prerequisites
-Before you are reading this guide you have to make sure you understand the basics of unit tests and how Jest works. You can find a good source for best practices in this Github Repo:
+Before you read this guide, make sure you understand the basics of unit testing and how Jest works. You can find a good source for best practices in this GitHub repo:
<PageRef page="https://github.com/goldbergyoni/javascript-testing-best-practices" title="Javascript testing - best practices @ GitHub" target="_blank" />
-In addition, you need a running Shopware 6 installation. Your repository used for that should be based on development template, as we will to use some scripts provided by it.
+In addition, you need a running Shopware 6 installation. Your repository for that should be based on the development template, as we will use some scripts provided by it.
-For one example, we use a Javascript plugin. In oder to follow this example, you need to know how to build a Javascript plugin in the first place. You can learn about it in the corresponding [guide](../storefront/add-custom-javascript/).
+For one example, we use a Javascript plugin. To follow this example, you need to know how to build a Javascript plugin in the first place. You can learn about it in the corresponding [guide](../../../plugins/plugins/storefront/add-custom-javascript.md).
## Test structure
::: warning
-When it comes to the path to the test folder, you are quite free to use your own requirements. You could even build up a separate test suite if you need. There's one limitation though: Please take care you place your tests according your `package.json` file!
+When it comes to the path to the test folder, you are free to use whatever you prefer. You could even build a separate test suite if needed. There's one limitation, though: please ensure you place your tests according to your `package.json` file!
:::
-The following configuration matches our core configuration in order to give you a starting point. In Shopware's platform repository, you will find the Storefront unit tests in the following directory: `platform/src/Storefront/Resources/app/storefront/test` It may be a good convention to resemble this directory structure, but it's no fixed requirement.
+The following configuration matches our core configuration to give you a starting point. In Shopware's platform repository, you will find the Storefront unit tests in the following directory: `platform/src/Storefront/Resources/app/storefront/test`. It may be a good convention to resemble this directory structure, but it's not a fixed requirement.
-Inside the test directory, you add a test for a file in the same path as the source path. You see: When creating the file, the name should also be the same as the component has with an additional `test`.
+Inside the test directory, you add a test for a file in the same path as the source path. You see: When creating the file, the name should match the component's name with an additional `test`.
-The exact test folder structure looks like seen below, starting in `Storefront` bundle:
+The exact test folder structure looks like what is seen below, starting in the `Storefront` bundle:
```bash
Resources
`-- app
- `-- <environment>
+ `-- <environment>
`-- test
- `-- plugin
+ `-- plugin
`-- <plugin-name>
- `-- js-plugin-test.spec.js
+ `-- js-plugin-test.spec.js
```
Please note that in this example, `<environment>` is a placeholder for the environment you are working in. In this context, that should be `storefront`.
## Writing a basic test
-When writing jest unit tests in the Storefront, you will soon realize that it's not that much different from writing jest unit tests in general. Unlike the [Jest unit tests in the Administration](jest-admin), you basically don't need to go an extra mile to write your unit tests. Services, helper and isolated ECMAScript modules are well testable because you can import them directly without mocking or stubbing dependencies. They can be used isolated and therefore are easy to test.
+When writing Jest unit tests in the Storefront, you will soon realize that it's not that much different from writing Jest unit tests in general. Unlike the [Jest unit tests in the Administration](jest-admin), you basically don't need to go the extra mile to write your unit tests. Services, helpers, and isolated ECMAScript modules are well testable because you can import them directly without mocking or stubbing dependencies. They can be used in isolation, making them easy to test.
-Let's start from scratch with a simple example: Imagine we want to write a test for a helper class, e.g. the `feature.helper` of our Storefront, handling the feature flag usage. We want to test, if our feature helper can indeed handle active feature flags.
+Let's start from scratch with a simple example: imagine we want to write a test for a helper class, e.g., the `feature.helper` of our Storefront, that handles feature flag usage. We want to test whether our feature helper can indeed handle active feature flags.
-At first, you need to create your test file, e.g. `feature.helper.test.js`. With your new created test file, let's create the test structure for it:
+First, create your test file, e.g., `feature.helper.test.js`. With your newly created test file, let's create the test structure for it:
```javascript
// <plugin root>/src/Resources/app/storefront/test/helper/feature.helper.test.js
@@ -67,11 +65,11 @@ describe('feature.helper.js', () => {
// This is your actual test
test('checks the flags', () => {
// Assertions come here
- });
+ });
});
```
-Now, let's fill this empty test with life. Our first step is importing the helper under test - the `feature.helper` class. However, there one more step to be done for preparation.
+Now, let's fill this empty test with life. Our first step is importing the helper under test - the `feature.helper` class. However, there is one more step to be done for preparation.
```javascript
// <plugin root>/src/Resources/app/storefront/test/helper/feature.helper.test.js
@@ -81,13 +79,13 @@ import Feature from 'src/helper/feature.helper';
describe('feature.helper.js', () => {
test('checks the flags', () => {
// Assertions come here
- });
+ });
});
```
-In order to be able to test our feature flag integration, we of course need some fixtures to be present - some active and inactive feature flags. So we need to ensure their presence before running the tests, ideally in a setup step. As you might know from other frameworks, it's convenient to use [lifecycle hooks](https://jestjs.io/docs/setup-teardown) for that purpose.
+To be able to test our feature flag integration, we of course need some fixtures to be present - some active and inactive feature flags. So we need to ensure their presence before running the tests, ideally in a setup step. As you might know from other frameworks, it's convenient to use [lifecycle hooks](https://jestjs.io/docs/setup-teardown) for that purpose.
-To sum it up, we need a feature flag fixture and the implementation of it in the `beforeEach` hook of our test. In our example, that looks like below:
+To sum it up, we need a feature flag fixture and its implementation in the `beforeEach` hook of our test. In our example, that looks like this:
```javascript
// <plugin root>/src/Resources/app/storefront/test/helper/feature.helper.test.js
@@ -105,15 +103,15 @@ describe('feature.helper.js', () => {
beforeEach(() => {
// Applying the flag fixture
Feature.init(default_flags);
- });
+ });
test('checks the flags', () => {
// Assertions come here
- });
+ });
});
```
-Alright, let's get to the point now, writing the actual test. Remember we want to make sure we have active and inactive feature flags. In addition, it may be useful to check the behavior if a third, non-existent feature flag is introduced. Using [Jest's matchers](https://jestjs.io/docs/using-matchers) for these assertions, we get the following test:
+Alright, let's get to the point now, writing the actual test. Remember, we want to ensure we have both active and inactive feature flags. In addition, it may be useful to check the behavior if a third, non-existent feature flag is introduced. Using [Jest's matchers](https://jestjs.io/docs/using-matchers) for these assertions, we get the following test:
```javascript
// <plugin root>/src/Resources/app/storefront/test/helper/feature.helper.test.js
@@ -127,27 +125,27 @@ const default_flags = {
describe('feature.helper.js', () => {
beforeEach(() => {
Feature.init(default_flags);
- });
+ });
test('checks the flags', () => {
expect(Feature.isActive('test1')).toBeTruthy();
expect(Feature.isActive('test2')).toBeFalsy();
expect(Feature.isActive('test3')).toBeFalsy();
- });
+ });
});
```
-That's basically it! We wrote our first jest unit test in the Storefront.
+That's basically it! We wrote our first Jest unit test in the Storefront.
## Executing the tests
-Before you are using the commands make sure that you installed all dependencies for your Storefront. If you haven't done this already, then you can do it running the following PSH command:
+Before you use the commands, make sure that you have installed all dependencies for your Storefront. If you haven't done this already, then you can do it by running the following PSH command:
```bash
> composer run build:js:storefront
```
-In order to run jest unit tests of the Storefront, you can use the psh commands provided by our development template. This command executes all unit tests and shows you the complete code coverage.
+To run Jest unit tests of the Storefront, you can use the psh commands provided by our development template. This command executes all unit tests and shows you the complete code coverage.
```bash
> composer run storefront:unit
@@ -159,13 +157,13 @@ This only applies to the Shopware provided Storefront! If you use unit tests in
## Mocking JavaScript plugins
-Now, let's have a look at a intermediate example: As you're writing JavaScript plugins, you may want to test those. As you need to mock some things in this case, this kind of test might be a bit more complex.
+Now, let's have a look at an intermediate example: As you're writing JavaScript plugins, you may want to test those. As you need to mock some things in this case, this kind of test might be a bit more complex.
::: info
-The folder structure, and the corresponding file locations of the following example will resemble the one used in `platform` repository.
+The folder structure and the corresponding file locations in the following example will resemble those used in the `platform` repository.
:::
-Let's start with the plugin we want to test later. For the sake of simplicity, we will use a plugin which returns "Hello world":
+Let's start with the plugin we'll test later. For the sake of simplicity, we will use a plugin that returns "Hello world":
```javascript
// <plugin root>/src/Resources/app/storefront/src/plugin/hello-world/hello-world.plugin.js
@@ -176,17 +174,17 @@ export default class HelloWorldPlugin extends Plugin {
init() {
console.log('Hello World!', this.el);
- }
+ }
sayHello() {
return "Hello World!"
- }
+ }
}
```
-Of course, you need to make sure that your plugin is registered, more details in the guide on [Javascript plugins](../storefront/add-custom-javascript/).
+Of course, you need to make sure your plugin is registered. For more details, see the guide on [Javascript plugins](../../../plugins/plugins/storefront/add-custom-javascript.md).
-In the beginning, writing plugin tests is still similar to other jest unit tests: You import your plugin's class and use the familiar test structure:
+In the beginning, writing plugin tests is still similar to other Jest unit tests: You import your plugin's class and use the familiar test structure:
```javascript
// <plugin root>/src/Resources/app/storefront/test/plugin/hello-world/hello-world.plugin.test.js
@@ -201,21 +199,21 @@ describe('HelloWorldPlugin tests', () => {
beforeEach(() => {
// Here we need to do all the mocking
- });
+ });
afterEach(() => {
// Teardown
- });
+ });
test('custom plugin exists', () => {
// your actual test
- });
+ });
});
```
-You might notice the lifecycle hook we use in this test. These will be important in the next steps where we begin to mock our plugin and clean it up after our tests.
+You might notice the lifecycle hook we use in this test. These will be important in the following steps, where we begin to mock our plugin and clean it up after our tests.
-The `beforeEach` hook will be executed before each test. Thus, it's the perfect location for creating our plugin under test. Therefore, we need to get an element first. We'll use it to create our plugin - resembling the usage of a plugin on an element.
+The `beforeEach` hook will be executed before each test. Thus, it's the perfect location for creating our plugin under test. Therefore, we need to get an element first. We'll use it to create our plugin, resembling the way a plugin is used on an element.
```javascript
// <plugin root>/src/Resources/app/storefront/test/plugin/hello-world/hello-world.plugin.test.js
@@ -235,16 +233,16 @@ describe('HelloWorldPlugin tests', () => {
const mockedElement = document.createElement('div');
plugin = new HelloWorldPlugin(mockedElement);
- });
+ });
afterEach(() => {
// Teardown
- });
+ });
test('custom plugin exists', () => {
- // your actual test, temporary filled with a placeholder
+ // your actual test, temporarily filled with a placeholder
console.log(plugin);
- });
+ });
});
```
@@ -260,14 +258,14 @@ If you execute your test now, you'll run into an error:
119 | */
120 | _registerInstance() {
- > 121 | const elementPluginInstances = window.PluginManager.getPluginInstancesFromElement(this.el);
- | ^
+ > 121 | const elementPluginInstances = window.PluginManager.getPluginInstancesFromElement(this.el);
+ | ^
122 | elementPluginInstances.set(this._pluginName, this);
123 |
124 | const plugin = window.PluginManager.getPlugin(this._pluginName, false);
```
-This was to be expected because you need to mock some more things required for the plugin to run. To solve this issue, you need to mock the `PluginManager` which holds all plugin instances globally in the Storefront. Because our test is just testing the single plugin class, the actual implementation on the real DOM element in the Storefront isn't too important at this moment.
+This was to be expected, since you need to mock more things required for the plugin to run. To solve this issue, you need to mock the `PluginManager`, which holds all plugin instances globally in the Storefront. Because our test is just testing the single plugin class, the actual implementation on the real DOM element in the Storefront isn't too important at this moment.
```javascript
// <plugin root>/src/Resources/app/storefront/test/plugin/hello-world/hello-world.plugin.test.js
@@ -286,32 +284,32 @@ describe('HelloWorldPlugin tests', () => {
window.PluginManager = {
getPluginInstancesFromElement: () => {
return new Map();
- },
+ },
getPlugin: () => {
return {
get: () => []
- };
- }
- };
+ };
+ }
+ };
const mockedElement = document.createElement('div');
plugin = new HelloWorldPlugin(mockedElement);
- });
+ });
afterEach(() => {
// Set your plugin to null to clean up afterwards
plugin = null;
- });
+ });
test('custom plugin exists', () => {
- // your actual test, temporary filled with a placeholder
+ // your actual test, temporarily filled with a placeholder
console.log(plugin);
- });
+ });
});
```
::: warning
-Don't forget the cleanup after each test! You need to set your plugin to `null` in your `afterEach` hook to ensure an isolated test.
+Don't forget to clean up after each test! Set your plugin to `null` in your `afterEach` hook to ensure an isolated test.
:::
Finally, we're ready to write our actual test. Write your assertions as you're used to. In this example, we first want to test if our plugin can be instantiated:
@@ -331,27 +329,27 @@ describe('HelloWorldPlugin tests', () => {
window.PluginManager = {
getPluginInstancesFromElement: () => {
return new Map();
- },
+ },
getPlugin: () => {
return {
get: () => []
- };
- }
- };
+ };
+ }
+ };
const mockedElement = document.createElement('div');
plugin = new HelloWorldPlugin(mockedElement);
- });
+ });
afterEach(() => {
plugin = null;
- });
+ });
test('The HelloWorld plugin can be instantiated', () => {
// Our assertions will be done here
expect(plugin).toBeInstanceOf(HelloWorldPlugin);
- });
+ });
});
```
@@ -361,10 +359,10 @@ Afterwards, we can add more tests as we want to. To give an example, it's useful
// <plugin root>/src/Resources/app/storefront/test/plugin/hello-world/hello-world.plugin.test.js
test('Shows text', () => {
expect(plugin.sayHello()).toBe('Hello World!')
- });
+ });
```
-Now you're ready to go! Below the full example of our test, for reference:
+Now you're ready to go! Below is the full example of our test, for reference:
```javascript
// <plugin root>/src/Resources/app/storefront/test/plugin/hello-world/hello-world.plugin.test.js
@@ -382,35 +380,30 @@ describe('HelloWorldPlugin tests', () => {
window.PluginManager = {
getPluginInstancesFromElement: () => {
return new Map();
- },
+ },
getPlugin: () => {
return {
get: () => []
- };
- }
- };
+ };
+ }
+ };
const mockedElement = document.createElement('div');
plugin = new HelloWorldPlugin(mockedElement);
- });
+ });
afterEach(() => {
// Teardown
plugin = null;
- });
+ });
test('The cookie configuration plugin can be instantiated', () => {
// your actual test
expect(plugin).toBeInstanceOf(HelloWorldPlugin);
- });
+ });
test('Shows text', () => {
expect(plugin.sayHello()).toBe('Hello World!')
- });
+ });
});
```
-
-## More interesting topics
-
-* [PHPUnit tests](php-unit/)
-* [End-to-end tests](end-to-end-testing/)
diff --git a/guides/plugins/plugins/testing/php-unit.md b/guides/development/testing/unit/php-unit.md
similarity index 72%
rename from guides/plugins/plugins/testing/php-unit.md
rename to guides/development/testing/unit/php-unit.md
index 5a4c0eacde..2e3edfc945 100644
--- a/guides/plugins/plugins/testing/php-unit.md
+++ b/guides/development/testing/unit/php-unit.md
@@ -7,19 +7,17 @@ nav:
# PHP Unit Testing
-## Overview
-
-This guide will cover the creation of PHPUnit tests in Shopware 6. Refer to the [official PHPUnit documentation](https://phpunit.de/documentation.html) for a deep dive into PHP unit testing.
+This guide covers creating PHPUnit tests in Shopware 6. Refer to the [official PHPUnit documentation](https://phpunit.de/documentation.html) for a deep dive into PHP unit testing.
## Prerequisites
-In order to create tests for a plugin, you need a plugin as a base. Refer to the [Plugin Base Guide](../plugin-base-guide) for more information.
+To create tests for a plugin, you need a plugin as a base. Refer to the [Plugin Base Guide](../../../plugins/plugins/plugin-base-guide.md) for more information.
-Furthermore, have a look at our [Execute database queries/migrations](../plugin-fundamentals/database-migrations) guide since this guide will show you how to create a migration test for these examples.
+Furthermore, refer to [migrations](../../../plugins/plugins/plugin-fundamentals/database-migrations.md) guide to create a migration test for these examples.
## PHPUnit configuration
-First, to configure PHPUnit, create a file called `phpunit.xml` in the root directory of the plugin. To get more familiar with the configurable options, refer to the [PHPUnit documentation](https://docs.phpunit.de/en/8.5/configuration.html). This example explains configuring PHPUnit to search in the directories `<plugin root>/src/Test` and `<plugin root>/src/Migration/Test` for your tests.
+First, to configure PHPUnit, create a file called `phpunit.xml` in the root directory of the plugin. To get more familiar with the configurable options, refer to the [PHPUnit documentation](https://docs.phpunit.de/en/8.5/configuration.html). This example explains how to configure PHPUnit to search for your tests in the directories `<plugin root>/src/Test` and `<plugin root>/src/Migration/Test`.
The `phpunit.xml` can be autogenerated for you with the `bin/console plugin:create` command:
@@ -63,22 +61,22 @@ This command will also generate a `TestBootstrap.php` file:
use Shopware\Core\TestBootstrapper;
$loader = (new TestBootstrapper())
- ->addCallingPlugin()
- ->addActivePlugins('BasicExample')
- ->setForceInstallPlugins(true)
- ->bootstrap()
- ->getClassLoader();
+ ->addCallingPlugin()
+ ->addActivePlugins('BasicExample')
+ ->setForceInstallPlugins(true)
+ ->bootstrap()
+ ->getClassLoader();
$loader->addPsr4('Swag\\BasicExample\\Tests\\', __DIR__);
```
-The `setForceInstallPlugins` method ensures that your plugin is installed and active even the test database was already build beforehand.
+The `setForceInstallPlugins` method ensures that your plugin is installed and active even if the test database was already built beforehand.
## Example Tests
### Integration test
-After PHPUnit is configured, a first test can be written. In this example, a test simply tries to instantiate every `.php` class to see if any used core classes are missing. In the test, you use the `IntegrationTestBehaviour` trait, which comes with some handy features, such as automatically setting up a database transaction or clearing the cache before starting tests.
+After PHPUnit is configured, the first test can be written. In this example, a test simply tries to instantiate every `.php` class to see if any of the core classes are missing. In the test, you use the `IntegrationTestBehaviour` trait, which provides handy features, such as automatically setting up a database transaction or clearing the cache before each test.
This is how your test could look like:
```php
@@ -96,28 +94,28 @@ class UsedClassesAvailableTest extends TestCase
use IntegrationTestBehaviour;
public function testClassesAreInstantiable(): void
- {
+ {
$namespace = str_replace('\Test', '', __NAMESPACE__);
foreach ($this->getPluginClasses() as $class) {
$classRelativePath = str_replace(['.php', '/'], ['', '\\'], $class->getRelativePathname());
$this->getMockBuilder($namespace . '\\' . $classRelativePath)
- ->disableOriginalConstructor()
- ->getMock();
- }
+ ->disableOriginalConstructor()
+ ->getMock();
+ }
// Nothing broke so far, classes seem to be instantiable
$this->assertTrue(true);
- }
+ }
private function getPluginClasses(): Finder
- {
+ {
$finder = new Finder();
$finder->in(realpath(__DIR__ . '/../'));
$finder->exclude('Test');
return $finder->files()->name('*.php');
- }
+ }
}
```
@@ -125,7 +123,7 @@ class UsedClassesAvailableTest extends TestCase
In order to test the example migration `Migration1611740369ExampleDescription`, create a new test called `Migration1611740369ExampleDescriptionTest`, which extends from the PHPUnit `TestCase`. Use the `KernelTestBehaviour` trait because a database connection from the container is needed.
-This is an example for a migration test:
+This is an example of a migration test:
```php
// <plugin root>/src/Migration/Test/Migration1611740369ExampleDescriptionTest.php
@@ -142,7 +140,7 @@ class Migration1611740369ExampleDescriptionTest extends TestCase
use KernelTestBehaviour;
public function testNoChanges(): void
- {
+ {
/** @var Connection $conn */
$conn = $this->getContainer()->get(Connection::class);
$expectedSchema = $conn->fetchAssoc('SHOW CREATE TABLE `swag_basic_example_general_settings`')['Create Table'];
@@ -156,10 +154,10 @@ class Migration1611740369ExampleDescriptionTest extends TestCase
$migration->updateDestructive($conn);
$actualSchema = $conn->fetchAssoc('SHOW CREATE TABLE `swag_basic_example_general_settings`')['Create Table'];
static::assertSame($expectedSchema, $actualSchema, 'Schema changed!. Run init again to have clean state');
- }
+ }
public function testNoTable(): void
- {
+ {
/** @var Connection $conn */
$conn = $this->getContainer()->get(Connection::class);
$conn->executeStatement('DROP TABLE `swag_basic_example_general_settings`');
@@ -169,15 +167,15 @@ class Migration1611740369ExampleDescriptionTest extends TestCase
$exists = $conn->fetchColumn('SELECT COUNT(*) FROM `swag_basic_example_general_settings`') !== false;
static::assertTrue($exists);
- }
+ }
}
```
## Mocking services
-In some cases a service should behave differently in a test run. Such a case could be where a service deletes a file or makes a critical api call. To avoid this in a test run it is possible to create a `<plugin root>/Resources/config/services_test.{xml|yml}` file which will override your `<plugin root>/Resources/config/services.{xml|yml}`. But only for the test environment.
+In some cases, a service should behave differently in a test run. Such a case could be where a service deletes a file or makes a critical api call. To avoid this in a test run, you can create a `<plugin root>/Resources/config/services_test.{xml|yml}` file that overrides your `<plugin root>/Resources/config/services.{xml|yml}`. But only for the test environment.
-In this test-only service config you can override arguments, aliases or parameters to change what the service container injects into services during a test run.
+In this test-only service config, you can override arguments, aliases, or parameters to change what the service container injects into services during a test run.
## Executing the test
@@ -207,15 +205,8 @@ To execute a specific test class or method of a testsuite, pass the argument `--
## Flex template
-In order to run PHPunit tests install the flex template [dev-tools](../../../../guides/installation/template.md#how-do-i-migrate-from-production-template-to-symfony-flex) package via composer.
+To run PHPunit tests install the flex template [dev-tools](../../../../guides/installation/template.md#how-do-i-migrate-from-production-template-to-symfony-flex) package via composer.
```shell
composer require --dev dev-tools
```
-
-## Next steps
-
-Running unit tests with javascript code is explained in the following two articles:
-
-* [Jest unit tests in Shopware's Administration](jest-admin)
-* [Jest unit tests in Shopware's Storefront](jest-storefront)
diff --git a/guides/integrations-api/general-concepts/api-versioning.md b/guides/integrations-api/general-concepts/api-versioning.md
deleted file mode 100644
index 5abebd5048..0000000000
--- a/guides/integrations-api/general-concepts/api-versioning.md
+++ /dev/null
@@ -1,90 +0,0 @@
----
-nav:
- title: API Versioning
- position: 40
-
----
-
-# API Versioning
-
-## Overview
-
-Starting with Shopware version 6.4.0.0, we have changed our API versioning strategy. This article covers what we've done and changed, how it used to be, and what the version strategy looks like now.
-
-### Versioning prior to 6.4.0.0
-
-Prior to Shopware 6.4.0.0, the API version was mainly found in the routes themselves.
-
-`/api/v3/example-route`
-
-By using the version, one can ensure that the application continues to work because we are not going to introduce breaking changes within a version. However, versions must still be removed from time to time, which can still break the application.
-
-More on this can be found in our guide [ADR regarding the API version removal](https://github.com/shopware/shopware/blob/trunk/adr/2020-12-02-removing-api-version.md) section.
-
-### Versioning starting with 6.3.5.0
-
-With Shopware 6.4.0.0, we removed the API version from the routes.
-
-**Old**:
-
-`/api/v3/example-route`
-
-**New**:
-
-`/api/example-route`
-
-The version inside the route will keep working with Shopware 6.3.\*, but it will be removed with the next major Shopware version, 6.4.0.
-
-### Deprecations
-
-Deprecations are now added with patch and minor releases but only removed with a major release. This has always been the case for the Core and is now adapted to the API.
-
-Also, deprecated fields and routes are now shown in the Swagger documentation. Have a look at the FAQ beneath to learn how to open Swagger. Have a look for the `@deprecated` annotation on routes or the `Deprecated` flag on entity fields to see which fields or routes are deprecated in the code.
-
-### Route and field availability
-
-The Swagger API reference now includes the necessary information about the route and field availability. For routes, this can look like this:
-
-
-
-Note the availability information.
-
-Same for fields, here is an example of how it would look like:
-
-
-
-### API expectations
-
-API expectations can be used as a request header to define the necessary conditions for the server side. Example conditions could be the Shopware version, the existence of plugins, or the version of a plugin. There are some examples:
-
-```text
-GET /api/test
-sw-expect-packages: shopware/core:~6.4
-```
-
-This would expect that at least Shopware with version 6.4 is installed.
-
-```text
-GET /api/test
-sw-expect-packages: shopware/core:~6.4,swag/paypal:*
-```
-
-This would expect that the Shopware version is at least 6.4 and PayPal is installed in any version.
-
-If the conditions are not met, the backend will answer with a *417 Expectation Failed* error.
-
-## FAQ
-
-### I ensure that my application will keep on working by using the version in the route. What now?
-
-Yes, this was necessary for the previous versioning strategy since breaks were also introduced with Shopware minor releases. The new versioning strategy comes with the benefit that breaks are only introduced with major releases, which were always breaking anyway. Thus, one route will keep working for you until the next major release.
-
-### How do I get the currently used version via the API?
-
-You can read the currently used version in the API as well. Starting with Shopware 6.3.5.0, you can use this route to fetch the current version: `GET /api/_info/version`
-
-Prior to that, the version was readable using the following route: `GET /api/v2/_info/config`
-
-### How do I open up the Stoplight page?
-
-Navigate to the following URL in your shop: `/api/_info/stoplightio.html`
diff --git a/guides/integrations-api/general-concepts/index.md b/guides/integrations-api/general-concepts/index.md
deleted file mode 100644
index 7a17689adf..0000000000
--- a/guides/integrations-api/general-concepts/index.md
+++ /dev/null
@@ -1,36 +0,0 @@
----
-nav:
- title: General Concepts
- position: 10
-
----
-
-# General Concepts
-
-Even though the Admin API and the Store API serve very different purposes, they have some commonalities handy to be aware of.
-
-## Querying data
-
-For the Admin API these apply to the `/search` endpoint, whilst for the Store API they apply to almost every endpoint that returns a list of records.
-
-It starts with a very simple underlying concept, which encapsulates your entire search description in one generic object, referred to as the **search criteria**.
-
-<PageRef page="search-criteria" />
-
-There are some additional instructions that can be specified using **request headers**.
-
-<PageRef page="request-headers" />
-
-## Documentation
-
-Here you find a common approach regarding the way that Shopware provides endpoint references for its APIs:
-
-<PageRef page="generated-reference" />
-
-## API versioning
-
-Starting with Shopware version 6.4.0.0, we changed our API versioning strategy. The following article will cover what has been done and changed, how it used to be and how the version strategy looks like now.
-
-<PageRef page="api-versioning" />
-
-These topics provide essential foundations for effective API development and usage in Shopware.
diff --git a/guides/integrations-api/index.md b/guides/integrations-api/index.md
deleted file mode 100644
index 784a91bc0f..0000000000
--- a/guides/integrations-api/index.md
+++ /dev/null
@@ -1,26 +0,0 @@
----
-nav:
- title: Integrations / API
- position: 40
-
----
-
-# Integrations/API
-
-Generally, Shopware provides two APIs that serve two aspects of integrations with our platform. Both APIs are based on HTTP and though they serve different use cases, they share some underlying concepts. We recommend understanding these concepts before diving deeper into either of the APIs.
-
-<PageRef page="general-concepts/" />
-
-## Customer-facing interactions - Store API
-
-Frontend applications usually provide interfaces for users \(customers\). These applications usually don't expose sensitive data and have two layers of users - anonymous and authenticated i.e., unregistered and registered. Payloads are usually small, performance and availability are critical.
-
-<PageRef page="https://shopware.stoplight.io/docs/store-api/7b972a75a8d8d-shopware-store-api" title="Store API Endpoint Reference" target="_blank" />
-
-## Backend-facing integrations - Admin API
-
-These integrations are characterized by the exchange of structured data, synchronizations, imports, exports and notifications. Performance is also important in terms of high data loads rather than fast response times. Consistency, error handling, and transaction-safety are critical.
-
-<PageRef page="https://shopware.stoplight.io/docs/admin-api/8d53c59b2e6bc-shopware-admin-api" title="Admin API Endpoint Reference" target="_blank" />
-
-Shopware's Store and Admin APIs offer essential technical resources for you to interact with and customize the platform's core functions, enabling tailored solutions and seamless integration.
diff --git a/guides/plugins/apps/app-scripts/data-loading.md b/guides/plugins/apps/app-scripts/data-loading.md
index 462352a907..03fc0944bc 100644
--- a/guides/plugins/apps/app-scripts/data-loading.md
+++ b/guides/plugins/apps/app-scripts/data-loading.md
@@ -80,8 +80,6 @@ The criteria object that is used inside the app scripts behaves and looks the sa
So please refer to that documentation to get an overview of what features can be used inside a criteria object.
-<PageRef page="../../../integrations-api/general-concepts/search-criteria" />
-
The criteria object can be assembled inside scripts as follows:
```twig
diff --git a/guides/plugins/plugins/testing/cypress/cypress-end-to-end-testing.md b/guides/plugins/plugins/testing/cypress/cypress-end-to-end-testing.md
deleted file mode 100644
index a0186f7ad9..0000000000
--- a/guides/plugins/plugins/testing/cypress/cypress-end-to-end-testing.md
+++ /dev/null
@@ -1,558 +0,0 @@
----
-nav:
- title: Cypress End-to-end testing
- position: 11
-
----
-
-# Cypress End-to-End Testing
-
-## Overview
-
-In end-to-end testing \(E2E testing in short\) real user workflows are simulated, whereby as many as possible functional areas and parts of the technology stack used in the application should be included. This way, we are able to put our UI under constant stress and ensure that Shopware's main functionalities are always working correctly.
-
-## Prerequisites
-
-To use Shopware E2E tests, at first you need to have a Shopware 6 installation running. Making sure, that your tests are reliable, you should have a clean installation. Cleanup means no categories, no products, no settings, nothing!
-
-The easiest way to clean up your installation is the initialization. Using the command `composer run init` Shopware 6 gets initialized clean and without demo data. Installation of E2E dependencies can be accomplished separately by running `npm install` in the E2E folder you're using, e.g. for Shopware Administration it's `src/Administration/Resources/app/administration/test/e2e`.
-
-Since our tests should run on an installation that is as close as possible to a release package, we use production mode. If you run the tests on a development environment, the test results may vary.
-
-On top of that, please make sure your shop has a theme assigned. When using `composer run e2e:open` or `run`, this is done automatically.
-
-This guide also won't teach you how to write Cypress tests in general. Please take a look at the official Cypress documentation for further guidance.
-
-<PageRef page="https://docs.cypress.io/" title="Cypress Documentation" target="_blank" />
-
-### Using our testsuite
-
-The [E2E platform testsuite package](https://github.com/shopwareArchive/e2e-testsuite-platform) contains commands and helpers supporting you while building E2E tests for Shopware 6. On top of that, test data management and custom commands are included as well. More on that here: [Command reference](../../../../resources/references/core-reference/commands-reference/).
-
-This test suite is built on top of [Cypress](https://www.cypress.io/) as well as the following Cypress plugins:
-
-* [cypress-select-tests](https://github.com/bahmutov/cypress-select-tests)
-* [cypress-log-to-output](https://github.com/flotwig/cypress-log-to-output)
-* [cypress-file-upload](https://github.com/abramenal/cypress-file-upload)
-
-Here you can find the npm package of our testsuite:
-
-<PageRef page="https://www.npmjs.com/package/@shopware-ag/e2e-testsuite-platform" title="@shopware-ag/e2e-testsuite-platform - npm" target="_blank" />
-
-Please have a look on our [cypress.json](https://github.com/shopwareArchive/e2e-testsuite-platform/blob/3.x/cypress.json), a few of our commands expect some configuration, e.g. viewportHeight and width, because the admin menu only opens if the viewport is wide enough.
-
-## Setup steps
-
-When you use our [Development template](https://github.com/shopwareArchive/development), we provide you some tooling scripts located in `dev-ops/e2e/actions`, to use E2E tests more comfortably.
-
-The`composer` scripts to run our E2E tests in CLI or in Cypress' test runner are explained in the paragraph [Executing e2e tests](end-to-end-testing/#executing-e2e-tests).
-
-<Tabs>
-<Tab title="Plugin setup">
-
-Depending on your environment \(administration or storefront\) please create the following folder structure:
-
-```text
-Resources
- `-- app
- `-- <environment>
- `-- test
- `-- e2e
- `-- cypress
- |-- fixtures
- |-- integration
- |-- plugins
- `-- support
-```
-
-We will cover the use of every folder in detail.
-
-Within the folder `Resources/app/<environment>/test/e2e`, please run `npm init -y` to generate a `package.json` file. It is very convenient to place a script inside the newly created `package.json` to run the tests locally. Please add the following section to do so:
-
-```javascript
-"scripts": {
- "open": "node_modules/.bin/cypress open"
-},
-```
-
-Now install this package with the following command:
-
-```text
-npm install @shopware-ag/e2e-testsuite-platform
-```
-
-As next step, please create a new file `e2e/cypress/plugins/index.js` with the following content:
-
-```javascript
-module.exports = require('@shopware-ag/e2e-testsuite-platform/cypress/plugins');
-```
-
-Finally, create a new file e2e/cypress/support/index.js with the following line:
-
-```javascript
-// Require test suite commands
-require('@shopware-ag/e2e-testsuite-platform/cypress/support');
-```
-
-</Tab>
-
-<Tab title="Platform: Developing with docker">
-If you are using docker, you don't need to install a thing: We use the [Cypress/Included image](https://github.com/cypress-io/cypress-docker-images/tree/master/included) to use Cypress in Docker completely.
-
-However, as we're using this image for running the test runner as well, you may need to do some configuration first. Based on this [guide](https://www.cypress.io/blog/run-cypress-with-a-single-docker-command) you need to forward the XVFB messages from Cypress out of the Docker container into an X11 server running on the host machine. The guide shows an example for Mac; other operating systems might require different commands.
-
-In case you're using Docker on Mac we have summarized the steps from the guide mentioned above, so you can follow these to prepare your environment to get the Test Runner up and running:
-
-**Install and configure XQuartz**
-
-Install XQuartz via [Homebrew](https://docs.brew.sh/Installation) or alternatively [download](https://www.xquartz.org/) it from the official homepage:
-
-```bash
-brew install --cask xquartz
-```
-
-Run XQuartz via CLI or open it from your Desktop:
-
-```bash
-open -a XQuartz
-```
-
-Got to `XQuartz > Preferences` (`⌘ + ,`) and enable `Allow connections from network clients`:
-
-
-
-::: warning
-Restart your Mac before proceeding with the following steps.
-:::
-
-**Configure your environment**
-
-Grab your IP address and save it to the environment variable `IP`:
-
-```bash
-IP=$(ipconfig getifaddr en0)
-```
-
-Depending on how you're connected you might have to use another interface instead of `en0`.
-
-Now set the `DISPLAY` environment variable:
-
-```bash
-DISPLAY=$IP:0
-```
-
-Add `$IP` to xhost's ACL:
-
-```bash
-xhost + $IP
-```
-
-::: danger
-It is **crucial** to set these environment variables in the **same terminal session** from where you will later run `psh e2e:open`!
-
-Make sure that the `DISPLAY` environment variable on your Mac is properly set **before** you start the containers as it will be **passed** to the Cypress container when the container is **created**.
-Updating the variable on your host won't update it in the container until it is re-created!
-:::
-</Tab>
-</Tabs>
-
-## Executing E2E tests
-
-<Tabs>
-<Tab title="Plugin setup">
-
-If you want to run E2E tests in your plugin, just switch to the folder `Resources/app/<environment>/test/e2e` and execute the following command:
-
-```bash
-CYPRESS_baseUrl=<your-url> npm run open
-```
-
-`<your-url>` means the Storefront-URL of your Shopware environment.
-
-It opens up the Cypress test runner which allows you to run and debug your tests, similar to the `e2e:open` command.
-
-::: danger
-Don't forget that you might need to adjust test cleanup and other environment-related things according to your plugin's setup.
-:::
-
-</Tab>
-
-<Tab title="Execution in platform project">
-If you use Docker for your development environment, you are able to start right away.
-
-To prepare your shopware installation, your environment and install dependencies, please run the following command as first step, **outside** of your docker container:
-
-```bash
- composer run e2e:setup
-```
-
-In our tests, we assume a clean shopware installation, so we strongly recommend to use `e2e:setup`. However, if your shopware installation is already clean and prepared, you can skip the preparation of your shopware installation by using the following command **inside** your docker container:
-
-```bash
- composer run e2e:prepare
-```
-
-Afterwards, just use the following command outside of your container to run the Cypress Test Runner:
-
-```bash
-composer run e2e:open
-```
-
-If you want to run the tests in CLI, please use the following command outside your container:
-
-```bash
-composer e2e:cypress -- run --spec="cypress/e2e/administration/**/*.cy.js"
-```
-
-or
-
-```bash
-composer e2e:cypress -- run --spec="cypress/e2e/storefront/**/*.cy.js"
-```
-
-To see a complete overview on all psh scripts for e2e tests, feel free to refer to our [e2e command reference](../../../../../resources/references/testing-reference/e2e-commands/).
-</Tab>
-</Tabs>
-
-## Writing your first test
-
-### Folder structure
-
-In Shopware platform, you can find the tests in `src/Administration/Resources/app/administration/test/e2e`. There you can find the following folder structure, depending on your environment being Administration or Storefront:
-
-```bash
-`-- e2e
- `-- cypress
- |-- fixtures
- `-- example.json
- |-- integration
- `-- testfile.spec.js
- |-- plugins
- `-- index.js
- |-- support
- |-- commands.js
- `-- index.js
- |--cypress.json
- `--cypress.env.json
-```
-
-In the `cypress` folder, all test related folders are located. Most things will take place in these four folders:
-
-* `fixtures`: Fixtures are used as external pieces of static data that can be used by your tests. You can use them
-
- with the `cy.fixture` command.
-
-* `integration`: By default, the test files are located here. A file with the suffix "\*.spec.js" is a test file that
-
- contains a sequence of tests, performed in the order defined in it.
-
-* `plugins`: Contains extensions or plugins. By default, Cypress will automatically include the plugins file before
-
- every single spec file it runs.
-
-* `support`: The support folder is a great place to put reusable behavior such as custom commands or global overrides in,
-
- that you want to be applied and available to all of your spec files.
-
-These two configuration files are important to mention as well:
-
-* `cypress.json`
-* `cypress.env.json`
-
- These are Cypress configuration files. If you need more information about them, take a look at the
-
- [Cypress configuration docs](https://docs.cypress.io/app/references/configuration).
-
-If you need to use this structure in a plugin, it is just the path to the `e2e` folder, which is slightly different. You can find the folder structure in the paragraph [Setup](cypress-end-to-end-testing#setup-steps).
-
-If you want to contribute to Shopware platform's tests, please ensure to place your test in one of those folders:
-
-```javascript
-`-- integration
- |-- catalogue
- |-- content
- |-- customer
- |-- general
- |-- media-marketing
- |-- order
- |-- rule-product-stream
- `-- settings
-```
-
-::: warning
-This is important because otherwise your test is not considered by our CI.
-:::
-
-### Test layout and syntax
-
-Cypress tests are written in Javascript. If you worked with Mocha before, you will be familiar with Cypress' test layout. The test interface borrowed from Mocha provides `describe()`, `context()`, `it()` and `specify()`.
-
-To have a frame surrounding your test and provide a nice way to keep your test organized, use `describe()` \(or `context()` as its alias\):
-
-```javascript
-describe('Test: This is my test file', () => {
- it('test something', () => {
- // This is your first test
- });
- it('tests something else', () => {
- // This is your second test
- });
-});
-```
-
-The `it()` functions within the `describe()` function are your actual tests. Similar to `describe()` and `context()`, `it()` is identical to `specify()`. However, for writing Shopware tests we focus on `it()` to keep it consistent.
-
-## Commands and assertions
-
-In Cypress, you use commands and assertions to describe the workflow you want to test.
-
-### Commands
-
-Commands are the actions you need to do in order to interact with the elements of your application and reproduce the workflow to test in the end.
-
-```javascript
-it('test something', () => {
- ...
- cy.get('.sw-grid__row--0')
- .contains('A Set Name Snippet')
- .dblclick();
- cy.get('.sw-grid__row--0 input')
- .clear()
- .type('Nordfriesisch')
- .click();
- ...
- });
-```
-
-You can chain commands by passing its return value to the next one. These commands may contain extra steps to take, e.g. a `click` or `type` operation.
-
-Cypress provides a lot of commands to represent a variety of steps a user could do. On top of that, our E2E testsuite contains a couple of [custom commands](../../../../../resources/references/testing-reference/e2e-custom-commands/) specially for Shopware.
-
-### Assertions
-
-Assertions describe the desired state of your elements, objects and application. Cypress bundles the Chai Assertion Library \(including extensions for Sinon and jQuery\) and supports both BDD \(expect/should\) and TDD \(assert\) style assertions. For consistency reasons, we prefer BDD syntax in Shopware's tests.
-
-```javascript
-it('test something', () => {
- ...
- cy.get('.sw-loader')
- .should('not.exist')
- .should('be.visible')
- .should('not.have.css', 'display', 'none');
- cy.get('div')
- .should(($div) => {
- expect($div).to.have.length(1)
- });
- ...
- });
-```
-
-## Hooks
-
-You might want to set hooks to run before a set of tests or before each test. At Shopware we use those to e.g. clean up Shopware itself, login to the Administration or to set the admin language.
-
-Cypress got you covered, similar to Mocha, by providing hooks. These can be used to set conditions that you can run before or after a set of tests or each test.
-
-```javascript
-describe('We are using hooks', function() {
- before(function() {
- // runs once before all tests in the block
- })
-
- beforeEach(function() {
- // runs before each test in the block
- })
-
- afterEach(function() {
- // runs after each test in the block
- })
-
- after(function() {
- // runs once after all tests in the block
- })
-})
-```
-
-### Build up and teardown
-
-As we mentioned before, we use these hooks to build up the ideal situation for our test to run. This includes cleaning up the tests' state - based on a clean Shopware installation. According to Cypress' [thoughts on anti-patterns](https://docs.cypress.io/guides/references/best-practices.html#Using-after-or-afterEach-hooks) we clean up the previous state of Shopware beforehand. The reason is pretty simple: You can't be completely sure to reach the `after` hook \(sometimes tests may fail\), the safer way to cleanup your tests is the `beforeEach` hook. On top of stability advantages, it's possible to stop the tests anytime without manual cleanup.
-
-## Handling test data
-
-It's important and necessary the E2E tests are isolated. This means that the test should create itself beforehand, all the data needed for running. Afterwards, state in the database and the browser must be removed completely. This way, the spec avoids dependencies to demo data or data from other tests and cannot be disturbed by those.
-
-One test should only test one workflow, the one it's written for. For example, if you want to test the creation of products, you should not include the creation of categories in your test, although its creation is needed to test the product properly. As best practise we recommend handling everything not related to the test using the [lifecycle hooks](https://docs.cypress.io/guides/core-concepts/writing-and-organizing-tests.html#Hooks) provided by Cypress.
-
-In Shopware platform, we use Shopware's REST API to create the data we need. As a result, our tests are able to focus on one single workflow without having to test the workflows which normally need to be done to provide the data we need. Another aspect of handling it this way is, that creating test data via API is faster than doing it inside the test.
-
-### Cypress' fixtures
-
-To define the request you send to Shopware and to set first test data, store as `json` file in the folder `e2e/cypress/fixtures`. You can use those files to provide fixed test data which can be used directly to create the desired entity without any further searching or processing. Fortunately, Cypress provides a way to handle those fixtures by default. The command `cy.fixture()` loads this fixed set of data located in a json file.
-
-In the example file below, this file is used in order to define and create a customer. So, it provides data so that the customer can be created in Shopware.
-
-```json
-{
- "customerNumber": "C-1232123",
- "salutation": "Mr",
- "firstName": "Pep",
- "lastName": "Eroni",
- "email": "test@example.com",
- "guest": true,
- "addresses": [
- {
- ...
- }
- ]
-}
-```
-
-::: warning
-Use only fields, which you can access in the UI / Storefront. Keep in mind that all tests in the file may use the fixture. So keep an eye on compatibility.
-:::
-
-A small note on ID usage: Using ids may be easier for finding elements, but it isn't a proper way for testing in every case - It depends on your application. You need to be 100% sure that the id is persistent and won't change between builds. Never use ids here if you cannot be 100% sure they will not change at all, e.g. in another build.
-
-::: info
-At our case at Shopware, Ids on UUID basis tend to change from one installation to the next, so they are not always suitable to be used as selector in your test.
-:::
-
-### API implementation
-
-Analogue to the Administration itself, the api access of the e2e test is based on [axios](https://www.npmjs.com/package/axios), a promise based HTTP client for the browser and node.js.
-
-Just like the Administration, we use services to access Shopware's REST API. Therefore, we use the ApiService to provide the basic methods for accessing the api. Located in `e2e/cypress/support/service/api.service.js`, ApiService is shared between all repositories and acts as a basis for all your next steps of creating fixtures. That implies that the axios implementation of all important api methods can be found there. This service acts as an interface: Next to the basic functions like get, post etc the request method is specified here as well as some Shopware-related methods which have to be available in all repositories.
-
-::: info
-Cypress provides an own axios-based way to handle requests in its command `cy.request`. However, Cypress commands are not real promises, see [Commands are not Promises](https://docs.cypress.io/guides/core-concepts/introduction-to-cypress.html#Commands-Are-Not-Promises). As we aim to parallelize the promises to fetch test data, we use our own implementation instead.
-:::
-
-### Services and commands
-
-In order to get all test fixture data applied to our Shopware installation, we use services to send the API requests to find, create or update the data we need. To access these services conveniently, we provide custom commands, which we'll cover a bit later. Let's continue with the general things first.
-
-All fixture services can be found in `cypress/support/service/`:
-
-```bash
-service
- |-- administration // this folder stores the Administration channel API services
- `-- <environment>
- `-- test
- `-- e2e
- `-- cypress
- |-- fixture
- |-- admin-api.service.js // Provides all methods which communicate with admin api directly
- `-- fixture.service.js // Provides all methods for general fixture handling
- |-- saleschannel // this one stores the sales channel API services
- `-- api.service.js // axios interface
-```
-
-If you want to use all known services, you can access them using custom commands. These commands can be found in `cypress/support/commands/api-commands.js` for general operation and `cypress/support/commands/fixture-commands.js` specifically for fixture handling.
-
-#### Default fixture command
-
-The stationary fixtures mentioned in the paragraph "Cypress' fixtures" can be sent to Shopware's REST API directly: In most cases Shopware does not need any additional data, like IDs or other data already stored in Shopware. That means the request can be sent, and the desired entity can be created immediately: You just need to use the `createDefaultFixture(endpoint, options = [])` command, as seen below:
-
-```javascript
- beforeEach(() => {
- cy.createDefaultFixture('tax');
- });
-```
-
-In this example, a tax rate will be created with the data provided based on the `json` file located in the `fixtures` folder. Let's look at the command in detail:
-
-```javascript
-Cypress.Commands.add('createDefaultFixture', (endpoint, data = {}, jsonPath) => {
- const fixture = new Fixture();
- let finalRawData = {};
-
- if (!jsonPath) {
- jsonPath = endpoint;
- }
-
- // Get test data from cy.fixture first
- return cy.fixture(jsonPath).then((json) => {
-
- // Merge fixed test data with possible custom one
- finalRawData = Cypress._.merge(json, data);
-
- // Create the fixture using method from fixture service
- return fixture.create(endpoint, finalRawData);
- });
-});
-```
-
-#### Commands of customised services
-
-You will notice soon that some entities need data which has already been created. That means you have to find out specific IDs or employ a completely different handling. In this case, your own service has to be created, located in `e2e/cypress/support/service`. Some examples for these services are:
-
-* Customer
-* Sales channel
-* Languages
-* Products
-
-In most cases, the usage of these services is similar to the basic ones already implemented. There are commands for each of those services provided by our E2E testsuite package. You don't need to define the API endpoint when using those commands. As these services are extending the `FixturesService`, all methods of it can be used in all other services as well.
-
-#### Writing your own customised service
-
-Let's look at the custom service `shipping.fixture.js`. This service is a rather simple example - It depicts a service in need of some customization for creating a shipping method correctly. With that being said, let's start.
-
-Your `ShippingFixtureService` has to extend the class `AdminFixtureService`. Afterwards, you create a function called `setShippingFixture(userData)` with the parameter `userData` for the data you want to use to create your shipping method. This way, your class should look like this:
-
-```javascript
-const AdminFixtureService = require('../fixture.service.js');
-
-class ShippingFixtureService extends AdminFixtureService {
- setShippingFixture(userData) {
- // Here we're going to create our shipping fixture
- }
-}
-
-module.exports = ShippingFixtureService;
-
-global.ShippingFixtureService = new ShippingFixtureService();
-```
-
-All custom services hold a distinct method for creating fixtures: First, it's important to collect the necessary data via REST API. This is done by filtering POST requests used in promises. In case of your our `ShippingFixtureService`, you need the ID of the rule you want to use for the availability, and the ID of the delivery time.
-
-```javascript
- const findRuleId = () => this.search('rule', {
- type: 'equals',
- value: 'Cart >= 0 (Payment)'
- });
- const findDeliveryTimeId = () => this.search('delivery-time', {
- type: 'equals',
- value: '3-4 weeks'
-});
-```
-
-The responses of these calls are used to provide the missing IDs for your final POST request. At first, we will merge the missing data with the existing data, then create our shipping method:
-
-```javascript
-return Promise.all([
- findRuleId(),
- findDeliveryTimeId()
-]).then(([rule, deliveryTime]) => {
- return this.mergeFixtureWithData(userData, {
- availabilityRuleId: rule.id,
- deliveryTimeId: deliveryTime.id
- });
-}).then((finalShippingData) => {
- return this.apiClient.post('/shipping-method?_response=true', finalShippingData);
-});
-```
-
-That's it! There you go: You have successfully created a customised service that sets up a shipping method in Shopware. Actually, we use this service in our platform test to create our shipping method as well. You can find the full service [here](https://github.com/shopwareArchive/e2e-testsuite-platform/blob/master/cypress/support/service/administration/fixture/shipping.fixture.js). So please look at this example to see the whole class.
-
-Below you will find some best practices and tricks we explored to help you with your testing tasks:
-
-* A source of information can be found in FieldCollection of the several EntityDefinition files. All fields belonging to an entity are defined there. For example, if you're searching for customer related data, please search for the `CustomerDefinition` in Shopware platform.
-* If you want to extract mandatory data that is not covered by the error message received with the API's response, it's useful to reproduce your workflow manually: E.g. if you need to find out what data is mandatory for creating a customer, try to save an empty one in the Administration. Keep an eye on the developer tools of your browser while doing so, especially on the preview and response section of your request. As you get your response, you can see what data is still missing.
-* If you need to set non-mandatory data, reproducing the above mentioned workflow is recommended as well: Even if the error response does not contain a readable error, you can still inspect it: All the relevant information is stored in 'data'. IDs can be found there directly, other relevant data is stored in "attributes".
-* Cypress' test runner can help you a lot with inspecting API requests. Just click on the request in the test runner's log to get a full print of it in your console.
-
-## More interesting topics
-
-* [Unit testing with PHPUnit](../php-unit)
-* [Jest unit tests in Shopware's administration](../jest-admin)
-* [Jest unit tests in Shopware's storefront](../jest-storefront)
diff --git a/guides/plugins/plugins/testing/cypress/index.md b/guides/plugins/plugins/testing/cypress/index.md
deleted file mode 100644
index 124ca83ff4..0000000000
--- a/guides/plugins/plugins/testing/cypress/index.md
+++ /dev/null
@@ -1,12 +0,0 @@
----
-nav:
- title: Cypress End-to-end testing
- position: 10
-
----
-
-# Cypress End-to-end testing
-
-:::warning
-Cypress will be deprecated in the future and is no longer maintained. We recommend using [Playwright](../playwright/index.md) for new projects.
-:::
diff --git a/guides/plugins/plugins/testing/index.md b/guides/plugins/plugins/testing/index.md
deleted file mode 100644
index b1cc8cfc68..0000000000
--- a/guides/plugins/plugins/testing/index.md
+++ /dev/null
@@ -1,36 +0,0 @@
----
-nav:
- title: Testing
- position: 80
-
----
-
-# Testing
-
-Robust testing is crucial for developing reliable and maintainable Shopware plugins and themes. Shopware provides tooling and guidance for several types of tests, ensuring your code is production-ready and meets community standards.
-
-## Unit Testing
-
-Unit testing is the base layer of an effective test strategy. Shopware supports both PHP backend logic and JavaScript components (for Storefront and Administration):
-
-Use PHPUnit to write and run backend unit tests for your PHP code.
-
-<PageRef page="php-unit" />
-
-Use Jest to test Storefront JS and Vue components following modern best practices.
-
-<PageRef page="jest-storefront" />
-
-Test custom Administration panel modules and components using Jest with the Shopware admin setup.
-
-<PageRef page="jest-admin" />
-
-## End-to-End (E2E) Testing
-
-For simulating real user journeys and integration scenarios, Shopware recommends end-to-end (E2E) testing. Playwright is the officially supported tool for automating entire workflows across the application.
-
-Automate browser interactions to verify plugins and customizations work as intended in real-world Shopware environments.
-
-<PageRef page="playwright/" />
-
-Refer to the individual guides for setup, examples, and best practices for each testing type.
diff --git a/resources/guidelines/index.md b/resources/guidelines/index.md
index a935d9e46a..9390fb03d4 100644
--- a/resources/guidelines/index.md
+++ b/resources/guidelines/index.md
@@ -13,10 +13,6 @@ The code section lays out the coding standards. This helps anyone understand and
<PageRef page="./code/" />
-The test section briefs you about best practices for writing end-to-end tests.
-
-<PageRef page="./testing/" />
-
The document section details you on the language style, grammar, markdown syntax, and documentation process.
<PageRef page="./documentation-guidelines/" />
diff --git a/resources/guidelines/testing/index.md b/resources/guidelines/testing/index.md
deleted file mode 100644
index 3416cd8aab..0000000000
--- a/resources/guidelines/testing/index.md
+++ /dev/null
@@ -1,10 +0,0 @@
----
-nav:
- title: Test
- position: 30
-
----
-
-# Testing
-
-Testing ensures software reliability, quality, and optimum performance. Detailed E2E testing and quality guidelines are described in the following sections.
diff --git a/resources/guidelines/testing/store/quality-guidelines-apps/index.md b/resources/guidelines/testing/store/quality-guidelines-apps/index.md
deleted file mode 100644
index f5c6b206c9..0000000000
--- a/resources/guidelines/testing/store/quality-guidelines-apps/index.md
+++ /dev/null
@@ -1,470 +0,0 @@
----
-nav:
- title: Quality guidelines for apps and themes in the app system
- position: 10
-
----
-
-# Quality Guidelines for apps and themes based on the app system in the Shopware Store
-
-> **Changelog**
->
->> 09/11/24: Quality guidelines for apps and themes based on app system.
->
->> 23/11/23: [Added - New rules for Checklist for app testing](#every-app-based-on-the-app-system)
->
->> 27/09/23: [Added - Identical name rule](#every-app-based-on-the-app-system)
->
->> 26/07/23: [Added - Name preset according to new naming scheme](#every-app-based-on-the-app-system)
-
-## The way we test apps and themes based on the app system
-
-It is always a good idea to review our test process before submitting your app for review.
-This ensures the quickest way for your app to be published.
-
-We perform the *first test*, and if successful, we do the *follow-up test* again with the most current Shopware version.
-
-The app is tested with the latest official Shopware 6 CE Version.
-
-::: info
-We always test with the [actual SW6 version](https://www.shopware.com/de/download/#shopware-6).
-So set it to the actual SW6 version e.g., shopware/testenv:6.6.6.
-Always test with the app`s highest supported Shopware version.
-:::
-
-[Test your app for the Shopware Store (DE):](https://www.youtube.com/watch?v=gLb5CmOdi4g) and EN version is coming soon.
-
-**Progressive Web App:** If your app is PWA compatible and you would like the PWA flag, please contact us at [alliances@shopware.com](mailto:alliances@shopware.com).
-
-## Checklist for app testing
-
-Could you be sure to use the most recent testing checklist from Shopware and not any other provider?
-Please pay attention to every point in this guide. We'll review it before you release your app.
-
-### Every app and theme based on the app system
-
-* We pay attention to the automatic code review and look for security issues and shopware coding standards in the manual code review.
-
-* We check the complete functionality of the app (separately sales channel configurations in the config.xml, the uninstallation and reinstallation procedure) and check for styling errors on every viewport.
-
-[Documentation for Extension Partner](https://docs.shopware.com/en/account-en/extension-partner/extensions?category=account-en/extension-partner#how-can-i-request-a-preview)
-
-::: info
-**Safe your app idea and get a preview in the store**
-If you already have an idea and don't want it to be snatched away, ensure you get it by creating a preview in your account.
-You can apply for this if you have maintained placeholder images for the store, meaningful use cases, highlight features, a description, and a release month without uploading any binary.
-:::
-
-## App / Theme store description
-
-The release to the English store is standard.
-As an app / theme will be released in both stores (German and International), the content must accurately translate 1:1 from English to German.
-
-* The mandatory number of characters is set in short and long descriptions. No blank spaces as fillers are allowed (EN/DE).
-* Check if the description makes sense and describe the use cases of your app.
-* Check if your configuration manual includes step-by-step instructions on how to configure and use your app.
-* Check if you have included enough screenshots showing the app in action in the Storefront and administration.
-* Check if the display name does not contain the terms "plugin" or "shopware".
-* Check if all images for the English store description contain the English language. **Please do not mix English with other languages in your screenshots. Screenshots in German for the German store description are optional.**
-* Check if you explained the setup of the app / theme and added a configuration manual.
-
-### Display Name
-
-According to the new naming scheme, extensions may no longer display the words "plugin" and "shopware" in their names.
-An extension with a name that directly reflects its functional purpose is permissible, even if it shares the same name as another extension.
-
-Also, the store-display name had to be used for `theme.json` or `manifest.xml`.
-
-### Short description
-
-(Min. 150 — max. 185 characters)—The app's short description must be unique and at least 150 characters long.
-Use the short description wisely, as the text will tease your app in the overview along with the "Customers also bought" and "Customers also viewed" recommendations.
-The short description is also published as a meta-description.
-
-### Description
-
-(Min. 200 characters)—The app / theme description must be at least 200 characters long and describe the app's/theme's functions in detail.
-
-* Inline styles will be stripped. The following HTML tags are allowed:
-
-```markdown
-<a> <p> <br> <b> <strong> <i> <ul> <ol> <li> <h2> <h3> <h4> <h5>
-```
-
-* **Tips:**
-
- * When it comes to increasing your app / theme sales, it is important that potential customers feel completely informed about your products and services.
- To this end, you should provide description, highlights, and features that are meaningful, detailed, and easy to understand, even for people with very minimal technical knowledge.
- Explain step-by-step how your app works and how to use it to achieve the desired result.
- Of course, your app description should be accompanied by clean HTML source code.
-
- * Video content increases awareness and trust and has proven to convert potential customers better than other content types.
- You can help your customers better understand your app or service with explainer videos, product demos, tutorials, etc.
- You can embed a maximum of 2 YouTube videos in your app description.
-
-::: info
- You can no longer advertise your Shopware certificates within the app description, in your app images, or in your manufacturer profile. The manufacturer/partner certificates are dynamically loaded at the end of each app description and published by us.
-:::
-
-### Images
-
-::: info
-Screenshots and preview images in English are standard. Only full English screenshots are accepted. Please do not mix English with other languages in your screenshots. Screenshots in German for the German store description are optional.
-:::
-
-Include several screenshots and descriptive images from the Storefront and backend that represent the app functionality.
-They must show the app "in action", its configuration options, and how to use it.
-We recommend uploading screenshots showing the mobile and desktop-view.
-
-Only images that represent or show the function of the extension may be used. Advertising for other extensions or services is not permitted.
-
-[How To - Add images and icons to extensions](https://docs.shopware.com/en/account-en/adding-pictures-and-icons/how-to)
-
-### Link to demoshop
-
-If you provide a demo shop, the link must be valid (the URL cannot contain `http:` or `https:`).
-Do not link to your test environments, as we will delete them automatically two weeks after they are created.
-
-### Personal data protection information
-
-If necessary, personal data protection information has to be set.
-If personal data of the customers (store operator and/or his customers) are processed with this extension according to Art. 28 DSGVO, the following information of the data processing company must be stored in the field "Subprocessor".
-
-If other companies are involved in the data processing of personal data, the same information must be stored accordingly for them in the field "Further subprocessors".
-
-### Configuration manual
-
-Explain how your app is installed and configured, how it works on a technical base, and how it can be used to achieve the desired result.
-Of course, your app manual should contain a setup guide and be accompanied by clean HTML source code.
-
-### Manufacturer Profile
-
-Your manufacturer profile must mandatorily contain accurate English and German descriptions and a manufacturer logo.
-You can find the manufacturer profile in your account under Shopware Account > Extension Partner > [Extension Partner profile](https://account.shopware.com/producer/profile).
-
-::: info
-The source code's descriptions, profiles, and instructions do not allow iframes, external scripts, or tracking pixels.
-Custom styles may not overwrite the original Shopware styles. External sources must be included via https.
-:::
-
-## Basic Guidelines
-
-### Testing functionality
-
-Due to our quality assurance, we check the app's / theme's complete functionality and test it wherever it impacts the administration or storefront.
-
-Also, every app / theme will be code-reviewed by one of our core-developer ensuring coding and security standards.
-
-### Extension master data/license
-
-Please enter the valid license you set in your Shopware account.
-You have to identify this license in the `manifest.xml` as well.
-
-::: info
-The chosen license can't be changed after adding your app / theme to your account.
-If you want to change the license later, add a new app based on the app system with a new technical name and upload the extension again.
-:::
-
-### Fallback language / Translations
-
-The installation is not always in English or German.
-Could you make sure that your app works in other languages as well?
-For example, if the customer has his installation in Spanish and your app is not yet available in this language, you should use the English translation as a fallback.
-
-If your app is available in more than one language (e.g., English, Spanish, French and German), these can be defined using the option "Translations into the following languages are available" (located in the “Description & images” section of your *Account*).
-
-We check for text snippets, `config.xml`, `manifest.xml`, or `theme.json`.
-
-### Valid preview images for the Shopware administration
-
-Preview images: There must be a preview image available in the *Extension Manager*.
-You must upload a valid favicon named plugin.png (png / 112 x 112 pixels) for the app.
-This favicon will help you identify your app in the Extension Manager module in the administration.
-The favicon has to be stored under `src/Resources/config/`.
-
-Also, provide a preview image for Themes in the *Theme Manager* and CMS elements in the *Shopping Experiences*.
-
-### Configuration per sales channel
-
-Apps that appear in the Storefront and use a `config.xml` must be able to be configured separately for each sales channel.
-
-### External links with rel="noopener"
-
-Every external link in the administration or Storefront must be marked as *rel="noopener" AND target="_blank"*.
-
-### Error messages and logging
-
-Error or informational messages can only be recorded in the event log of Shopware's log folder (/var/log/).
-You have to develop your own log service.
-Never write app exceptions into the Shopware default log or outside the Shopware system log folder.
-This ensures that the log file can never be accessed via the URL.
-
-### Avoid 400/500 Error
-
-*Avoid 500 errors at any time.* Avoid 400 errors unless they are related to an API call.
-
-### Not allowed to extend the Extension Manager
-
-The *Extension Manager* must not be extended or overwritten.
-
-### Extension manager
-
-The Debug Console controls the app's installation, uninstallation, reinstallation, and deletion.
-No 400 errors or exceptions are allowed to appear. If the app requires special PHP options, it must be queried during installation.
-If the query is negative, a growl message must appear in the administration.
-
-### Reloading of files not allowed
-
-Apps / Themes may not load other files during and after the installation in the *Extension Manager*.
-
-### Uncompiled JavaScript must be delivered within the binary
-
-Compiled JavaScript offers many benefits such as improved performance and code optimization.
-However, it is difficult to read and understand the compiled code.
-The uncompiled JavaScript code must be placed in a separate folder to ensure it remains accessible to all developers.
-This allows other developers to review and understand the code in its original, readable form.
-
-Please build your `main.js` as described in our documentation and create the minified code as described in our developer documentation.
-
-[Loading the JS files](../../../../../guides/plugins/plugins/administration/module-component-management/add-custom-field.md#loading-the-js-files)
-
-[Injecting into the Administration](../../../../../guides/plugins/plugins/administration/module-component-management/add-custom-field.md#injecting-into-the-administration)
-
-Shopware reserves the right to publish extensions with minified code after individual consideration and consultation with the developer.
-For this, the developer must ensure that Shopware has access to the current unminified code of the extension at all times.
-
-### Message queue
-
-If the extension adds messages to the message queue, ensure they are not bigger than 262,144 bytes (256 KB).
-This limitation is set by common message queue workers and should not be exceeded.
-
-### Note on Shopware technology partner contract for interfaces
-
-You have now read the complete list of requirements for developing and releasing apps based on our app system in the Shopware Community Store.
-
-If your app is a software app/interface with downstream costs, transaction fees, or service fees for the customer, we need to complete a technology partner agreement in order to activate your app.
-
-If you have any questions regarding the technology partner agreement, please contact our sales team by writing an email to [alliances@shopware.com](mailto:alliances@shopware.com) or calling **+44 (0) 203 095 2445 (UK) / 00 800 746 7626 0 (worldwide) / +49 (0) 25 55 / 928 85-0 (Germany)**.
-
-## Storefront Guidelines
-
-### Testing the storefront
-
-Test the frontend and the checkout for new errors throughout the entire Storefront using the Browser Debug Console and also pay attention to JavaScript errors.
-
-### Links must include a title tag
-
-Links in the storefront and administration must include a meaningful "title tag".
-
-### Images must include the alt-tag
-
-Links in the storefront and administration must include a meaningful "alt tag" or the original alt tag from the media manager.
-
-### Do not use `<hX>`-Tags
-
-The utilization of `<hX>`-tags in the storefront templates, which are set to `<meta name="robots" content="index,follow">`, is not permissible, as these tags are reserved exclusively for content purposes.
-However, you may employ `<span class="h2">`, for instance.
-
-### Do not use inline-css in the storefront templates
-
-Use your own classes and let your CSS be compiled by the app.
-
-[Add SCSS variables](../../../../../guides/plugins/plugins/storefront/add-scss-variables.md#add-scss-variables)
-
-### Prevent `!important` usage
-
-Please avoid using the `!important` rule whenever possible.
-
-### New controller URLs / XHR requests
-
-We check for new XHR/Document requests in the storefront as they must be accompanied by an `X-Robots-Tag` in the header request with the directive "noindex, nofollow.".
-For further details, please refer to the [robots meta tag](https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag?hl=de#xrobotstag) article.
-
-If the app creates its own controller URLs set to "index, follow" and the URLs are accessible via the frontend, then these "app URLs" must also appear in the `sitemap.xml`.
-In addition, these pages must include a valid canonical tag, their own meta description, and a title tag, which can be entered individually via the administration or as a text snippet.
-
-### Lighthouse A/B-Testing
-
-Could you do an A/B test with *Lighthouse Audit* to check the performance and quality of your frontend app?
-There should not be any drastic change in performance, accessibility values, or any new errors when activating the app.
-
-* **Testing tool** for A/B-Testing:
- * [Google Lighthouse](https://developer.chrome.com/docs/lighthouse)
-
-### schema.org/Rich Snippets A/B-Testing
-
-Do an A/B-Test with *Scheme.org's Structured Data Testing Tool* and *Google Rich Result Tester* to check the homepage, categories, and various product detail pages (incl. available products, unavailable products, products with no review, single review, many reviews with various ratings, out-of-stock products, products to be released in the future or any other kind of product configuration and products including ean, mpn, width, length, height, weight).
-Also, could you check for duplicate entries as well as any new bugs?
-
-* **Testing tool** for A/B-Testing:
- * [Schema Markup Validator of schema.org](https://validator.schema.org/)
- * [Google Rich Result Tester] (<https://search.google.com/test/rich-results>)
-
-### Usage of fonts from external sources
-
-If you are using external fonts (e.g., Google fonts, Fontawesome) or external services, the app store description must contain this information.
-
-Please be aware that you might have to edit your *data protection information*.
-This info could be placed as a tooltip near the font settings of the app configuration.
-
-### Register your cookie to the Cookie Consent Manager
-
-We expect every cookie set from the store URL to be optional and not technically required for running shopware.
-Therefore, the cookies had to be [registered in our Cookie Consent Manager](../../../../../guides/plugins/apps/storefront/cookies-with-apps.md).
-
-We differentiate between "Technically required", ,"Marketing" and "Comfort features".
-All cookies must appear (unchecked) in the cookie configuration box in the frontend.
-
-## Administration guidelines
-
-### Menu entries in the main menu are not allowed
-
-Menu entries in the main menu of the administration are not allowed because of the look and feel.
-
-### Own media folder
-
-Manufacturer must create their own media folders with the right thumbnail settings or use existing ones to upload images, except for upload fields within the `config.xml`.
-
-If you use your own media folder, keep in mind that the folder and the included data had to be removed if selected during the uninstallation.
-
-### Shopping experiences
-
-[Shopping worlds elements](../../../../../concepts/commerce/content/shopping-experiences-cms.md#elements) must include an element icon.
-If the app is deleted, *Shopping Worlds* should work flawlessly in the frontend.
-
-### Themes
-
-[Themes](../../../../../guides/plugins/themes/) must include its own preview image.
-
-### External technology/ Shopware Technology Partner (STP) apps
-
-Every external technology app needs to track its commission.
-Below is an example of implementing the tracking logic in their extensions:
-
-// POST /shopwarepartners/reports/technology - Allows partners to send us the info based on the STP contract
-
-```json
- {
- "identifier": "8e167662-6bbb-11eb-9439-0242ac130002",
- "reportDate": "2005-08-15T15:52:01",
- "instanceId": "alur24esfaw3ghk",
- "shopwareVersion": "6.3.1",
- "reportDataKeys": [
- {
- "customer": 3
- },
- {
- "turnover": 440
- }
- ]
- }
-```
-
-### Automatic code reviews with PhpStan and SonarQube
-
-Our most current code review configurations when uploading apps via the Shopware Account can be found on GitHub.
-
-* [Code reviews for Shopware 6 on GitHub](https://github.com/shopwareLabs/store-plugin-codereview)
-
-### Sonarcube Rules status Blocker
-
-The following statements will be blocked as of 1st Oct. 2022:
--die; exit; var_dump
-
-[Refer to the list of the already existing blockers](https://s3.eu-central-1.amazonaws.com/wiki-assets.shopware.com/1657519735/blocker.txt).
-
-### Useful tool for app development and extension management
-
-The [`shopware-cli`](https://github.com/shopware/shopware-cli) is a useful tool for building, validating and uploading new Shopware 6 app releases to the Community Store. It also allows you to manage the store description and images of your apps efficiently.
-
-## Automatic code review - Errors
-
-### The required manifest.xml file was not found
-
-**Cause:** Error in manifest.xml
-
-One possible cause is that the technical app name from the Community Store or Account does not match the technical name entered in manifest.xml, or the app is incorrectly zipped.
-The technical app name must be stored in the first part of manifest.xml.
-Most of the errors are caused by the wrong technical name.
-For example, "Swag\\MyPlugin\\SwagMyPluginSW6" instead of "Swag\\MyPlugin\\SwagMyPlugin".
-
-[Example of a valid manifest.xml](../../../../../resources/references/app-reference/manifest-reference.md#manifest-reference)
-
-### Ensure cross-domain messages are sent to the intended domain
-
-When using `postMessage()` or similar cross-window messaging APIs, verify the message origin (e.g. `event.origin`) and restrict target domains to trusted URLs instead of `'*'`. This prevents malicious sites from sending or receiving unauthorized messages.
-
-### Class Shopware\Storefront\* not found
-
-Missing requirements in the theme.json (e.g. "require": {"shopware/frontend": "*"},)
-
-[Shopware App Development: App Meta Information - Explanation of the properties](../../../../../guides/plugins/plugins/plugin-base-guide#the-composerjson-file)
-
-### Cookies are written safely
-
-Be sure you set cookies as secure.
-Remember to register your cookie to the *Cookie Consent Manager*.
-
-### The lock file is not up to date with the latest changes in manifest.xml
-
-You may need to get updated dependencies. Run an update to update them.
-
-The `composer.lock` in the app archive has to be deleted.
-
-### Remove out-commented code from your source-code
-
-### Unauthorized file formats or folders detected in the app
-
-Remove out-commented code, unused files and folders, and all dev-files from your binary.
-
-Here are some examples of not allowed folders and files:
-
-* ./tests
-* .DS_Store
-* .editorconfig
-* .eslintrc.js
-* .git
-* .github
-* .gitignore
-* .gitkeep
-* .gitlab-ci.yml
-* .gitpod.Dockerfile
-* .gitpod.yml
-* .phar
-* .php-cs-fixer.cache
-* .php-cs-fixer.dist.php
-* .php_cs.cache
-* .php_cs.dist
-* .prettierrc
-* .stylelintrc
-* .stylelintrc.js
-* .sw-zip-blacklist
-* .tar
-* .tar.gz
-* .travis.yml
-* .zip
-* .zipignore
-* ISSUE_TEMPLATE.md
-* Makefile
-* Thumbs.db
-* __MACOSX
-* auth.json
-* bitbucket-pipelines.yml
-* build.sh
-* composer.lock
-* eslint.config.js
-* grumphp.yml
-* package-lock.json
-* package.json
-* phpdoc.dist.xml
-* phpstan-baseline.neon
-* phpstan.neon
-* phpstan.neon.dist
-* phpunit.sh
-* phpunit.xml.dist
-* phpunitx.xml
-* psalm.xml
-* rector.php
-* shell.nix
-* stylelint.config.js
-* webpack.config.js
diff --git a/resources/guidelines/testing/store/quality-guidelines-plugins/index.md b/resources/guidelines/testing/store/quality-guidelines-plugins/index.md
deleted file mode 100644
index 6b411cc442..0000000000
--- a/resources/guidelines/testing/store/quality-guidelines-plugins/index.md
+++ /dev/null
@@ -1,555 +0,0 @@
----
-nav:
- title: Quality guidelines for apps in the plugin system
- position: 10
-
----
-
-# Quality Guidelines for the Plugin System in the Shopware Store
-
-> **Changelog**
->
->> 09/10/24: Quality guidelines for apps in the plugin system.
->
->> 01/08/24: [Added - Message queue](..//quality-guidelines-plugins/#message-queue)
->
->> 06/09/23: [Added - Rules for own composer dependencies](../quality-guidelines-plugins/#own-composer-dependencies)
->
->> 26/07/23: [Added - Identical name rule](../quality-guidelines-plugins/#every-app-based-on-the-plugin-system)
-
-## The way we test apps based on the plugin system
-
-It is always a good idea to review our test process before submitting your app for review.
-This ensures the quickest way for your app to be published.
-
-We perform the *first test*, and if successful, we do the *follow-up test* again with the most current Shopware version.
-
-The app is tested with the latest official Shopware 6 CE Version.
-
-::: info
-We always test with the [actual SW6 version](https://www.shopware.com/de/download/#shopware-6).
-So set it to the actual SW6 version e.g., shopware/testenv:6.6.6.
-Always test with the app`s highest supported Shopware version.
-:::
-
-Link: [Test your app for the Shopware Store (DE):](https://www.youtube.com/watch?v=gLb5CmOdi4g) and EN version is coming soon.
-
-**Progressive Web App:** If your app is PWA compatible and you would like the PWA flag, please contact us at [alliances@shopware.com](mailto:alliances@shopware.com).
-
-## Checklist for app testing
-
-Could you be sure to use the most recent testing checklist from Shopware and not any other provider?
-Please pay attention to every point in this guide. We'll review it before you release your app.
-
-### Every app based on the plugin system
-
-* We pay attention to the automatic code review and look for security issues and shopware coding standards in the manual code review.
-
-* We check the complete functionality of the app (separately sales channel configurations in the config.xml, the uninstallation and reinstallation procedure) and check for styling errors on every viewport.
-
-Link: [Documentation for Extension Partner](https://docs.shopware.com/en/account-en/extension-partner/extensions?category=account-en/extension-partner#how-can-i-request-a-preview)
-
-::: info
-**Safe your app idea and get a preview in the store**
-If you already have an idea and don't want it to be snatched away, ensure you get it by creating a preview in your account.
-You can apply for this if you have maintained placeholder images for the store, meaningful use cases, highlight features, a description, and a release month without uploading any binary.
-:::
-
-## App store description
-
-The release to the English store is standard.
-As an app will be released in both stores (German and International), the content must accurately translate 1:1 from English to German.
-
-* The mandatory number of characters is set in short and long descriptions. No blank spaces as fillers are allowed (EN/DE).
-* Check if the description makes sense and describe the use cases of your app.
-* Check if your configuration manual includes step-by-step instructions on how to configure and use your app.
-* Check if you have included enough screenshots showing the app in action in the Storefront and administration.
-* Check if the display name does not contain the terms "plugin" or "shopware".
-* Check if all images for the English store description contain the English language. **Please do not mix English with other languages in your screenshots. Screenshots in German for the German store description are optional.**
-* Check if you explained the setup of the app and added a configuration manual.
-
-### Display Name
-
-According to the new naming scheme, extensions may no longer display the words "plugin" and "shopware" in their names.
-An extension with a name that directly reflects its functional purpose is permissible, even if it shares the same name as another extension.
-
-Also, the store-display name had to be used for `composer.json` and `config.xml`.
-
-### Short description
-
-(Min. 150 — max. 185 characters)—The app's short description must be unique and at least 150 characters long.
-Use the short description wisely, as the text will tease your app in the overview along with the "Customers also bought" and "Customers also viewed" recommendations.
-The short description is also published as a meta-description.
-
-### Description
-
-(Min. 200 characters)—The app description must be at least 200 characters long and describe the app's functions in detail.
-
-* Inline styles will be stripped. The following HTML tags are allowed:
-
-```markdown
-<a> <p> <br> <b> <strong> <i> <ul> <ol> <li> <h2> <h3> <h4> <h5>
-```
-
-* **Tips:**
-
- * When it comes to increasing your app sales, it is important that potential customers feel completely informed about your products and services.
- To this end, you should provide description, highlights, and features that are meaningful, detailed, and easy to understand, even for people with very minimal technical knowledge.
- Explain step-by-step how your app works and how to use it to achieve the desired result.
- Of course, your app description should be accompanied by clean HTML source code.
-
- * Video content increases awareness and trust and has proven to convert potential customers better than other content types.
- You can help your customers better understand your app or service with explainer videos, product demos, tutorials, etc.
- You can embed a maximum of 2 YouTube videos in your app description.
-
-::: info
-You can no longer advertise your Shopware certificates within the app description, in your app images, or in your manufacturer profile.
-The manufacturer/partner certificates are dynamically loaded at the end of each app description and published by us.
-:::
-
-### Images
-
-::: info
-Screenshots and preview images in English are standard. Only full English screenshots are accepted. Please do not mix English with other languages in your screenshots. Screenshots in German for the German store description are optional.
-:::
-
-Include several screenshots and descriptive images from the Storefront and backend that represent the app functionality.
-They must show the app "in action", its configuration options, and how to use it.
-We recommend uploading screenshots showing the mobile and desktop-view.
-
-Only images that represent or show the function of the extension may be used. Advertising for other extensions or services is not permitted.
-
-Link: [How To - Add images and icons to extensions](https://docs.shopware.com/en/account-en/adding-pictures-and-icons/how-to)
-
-### Link to demoshop
-
-If you provide a demo shop, the link must be valid (the URL cannot contain `http:` or `https:`).
-Do not link to your test environments, as we will delete them automatically two weeks after they are created.
-
-### Personal data protection information
-
-If necessary, personal data protection information has to be set.
-If personal data of the customers (store operator and/or his customers) are processed with this extension according to Art. 28 DSGVO, the following information of the data processing company must be stored in the field "Subprocessor".
-
-If other companies are involved in the data processing of personal data, the same information must be stored accordingly for them in the field "Further subprocessors".
-
-### Configuration manual
-
-Explain how your app is installed and configured, how it works on a technical base, and how it can be used to achieve the desired result.
-Of course, your app manual should contain a setup guide and be accompanied by clean HTML source code.
-
-### Manufacturer Profile
-
-Your manufacturer profile must mandatorily contain accurate English and German descriptions and a manufacturer logo.
-You can find the manufacturer profile in your account under Shopware Account > Extension Partner > [Extension Partner profile](https://account.shopware.com/producer/profile).
-
-::: info
-The source code's descriptions, profiles, and instructions do not allow iframes, external scripts, or tracking pixels.
-Custom styles may not overwrite the original Shopware styles. External sources must be included via https.
-:::
-
-## Basic Guidelines
-
-### Testing functionality
-
-Due to our quality assurance, we check the app's complete functionality and test it wherever it impacts the administration or storefront.
-
-Also, every app will be code-reviewed by one of our core-developer ensuring coding and security standards.
-
-### Extension master data/license
-
-Please enter the valid license you set in your Shopware account.
-You have to identify this license in the `composer.json` as well.
-
-::: info
-The chosen license can't be changed after adding your app to your account.
-If you want to change the license later, add a new app based on the app system with a new technical name and upload the extension again.
-:::
-
-### Fallback language / Translations
-
-The installation is not always in English or German.
-Could you make sure that your app works in other languages as well?
-For example, if the customer has his installation in Spanish and your app is not yet available in this language, you should use the English translation as a fallback.
-
-If your app is available in more than one language (e.g., English, Spanish, French and German), these can be defined using the option "Translations into the following languages are available" (located in the "Description & images" section of your *Account*).
-
-We check for text snippets, `config.xml`, and `composer.json`.
-
-### Valid preview images for the Shopware administration
-
-Preview images: There must be a preview image available in the *Extension Manager*.
-You must upload a valid favicon named plugin.png (png / 112 x 112 pixels) for the app.
-This favicon will help you identify your app in the Extension Manager module in the administration.
-The favicon has to be stored under `src/Resources/config/`.
-
-Also, provide a preview image for Themes in the *Theme Manager* and CMS elements in the *Shopping Experiences*.
-
-### Configuration per sales channel
-
-Apps that appear in the Storefront and use a `config.xml` must be able to be configured separately for each sales channel.
-
-### External links with rel="noopener"
-
-Every external link in the administration or Storefront must be marked as *rel="noopener" AND target="_blank"*.
-
-### Error messages and logging
-
-Error or informational messages can only be recorded in the event log of Shopware's log folder (/var/log/).
-You have to develop your own log service.
-Never write app exceptions into the Shopware default log or outside the Shopware system log folder.
-This ensures that the log file can never be accessed via the URL.
-
-For payment apps, we check if the "plugin logger" service is used for the debug/error.log and that logs are written in the directory /var/log/. Log files must be used in every circumstance.
-
-The log file had to be named like this: "MyExtension-Year-Month-Day.log"
-
-Another solution is to store them in the database.
-Try to avoid using your own log tables. Otherwise, you have to implement a scheduled task that regularly empties your log table within the given time of max. 6 months.
-
-### Avoid 400/500 Error
-
-*Avoid 500 errors at any time.* Avoid 400 errors unless they are related to an API call.
-
-### With "Install/Uninstall" the user must decide whether the data/table is to be deleted or not
-
-When clicking on the "Install / Uninstall" option in the Extension Manager, the user must be presented with the options "completely delete" or "keep the app data, text snippets, media folder including own media and table adjustments".
-You can check this using the Adminer-App from *Friends of Shopware* in your provided test-environment.
-
-### Not allowed to extend the Extension Manager
-
-The *Extension Manager* must not be extended or overwritten.
-
-### Own composer dependencies
-
-Composer dependencies are possible if they are in the `composer.json`.
-With `executeComposerCommands() === true` in the plugin base class, we provide a dynamic installation of the composer dependencies by default, so they don't have to be included.
-Everything that is delivered in code should be traceable either directly or via `composer.json`.
-
-[Developer documentation article to add private dependency](../../../../../guides/plugins/plugins/plugin-fundamentals/using-composer-dependencies)
-
-### Extension manager
-
-The Debug Console controls the app's installation, uninstallation, reinstallation, and deletion.
-No 400 errors or exceptions are allowed to appear. If the app requires special PHP options, it must be queried during installation.
-If the query is negative, a growl message must appear in the administration.
-
-### Reloading of files not allowed
-
-Apps may not load other files during and after the installation in the *Extension Manager*.
-
-### Uncompiled JavaScript must be delivered within the binary
-
-Compiled JavaScript offers many benefits such as improved performance and code optimization.
-However, it is difficult to read and understand the compiled code.
-The uncompiled JavaScript code must be placed in a separate folder to ensure it remains accessible to all developers.
-This allows other developers to review and understand the code in its original, readable form.
-
-Please build your `main.js` as described in our documentation and create the minified code as described in our developer documentation.
-
-[Loading the JS files](../../../../../guides/plugins/plugins/administration/module-component-management/add-custom-field.md#loading-the-js-files)
-
-[Injecting into the Administration](../../../../../guides/plugins/plugins/administration/module-component-management/add-custom-field.md#injecting-into-the-administration)
-
-Shopware reserves the right to publish extensions with minified code after individual consideration and consultation with the developer.
-For this, the developer must ensure that Shopware has access to the current unminified code of the extension at all times.
-
-### Message queue
-
-If the extension adds messages to the message queue, ensure they are not bigger than 262,144 bytes (256 KB).
-This limitation is set by common message queue workers and should not be exceeded.
-
-### Note on Shopware technology partner contract for interfaces
-
-You have now read the complete list of requirements for developing and releasing apps based on our app system in the Shopware Community Store.
-
-If your app is a software app/interface with downstream costs, transaction fees, or service fees for the customer, we need to complete a technology partner agreement in order to activate your app.
-
-If you have any questions regarding the technology partner agreement, please contact our sales team by writing an email to [alliances@shopware.com](mailto:alliances@shopware.com) or calling **+44 (0) 203 095 2445 (UK) / 00 800 746 7626 0 (worldwide) / +49 (0) 25 55 / 928 85-0 (Germany)**.
-
-## Storefront Guidelines
-
-### Testing the storefront
-
-Test the frontend and the checkout for new errors throughout the entire Storefront using the Browser Debug Console and also pay attention to JavaScript errors.
-
-### Links must include a title tag
-
-Links in the storefront and administration must include a meaningful "title tag".
-
-### Images must include the alt-tag
-
-Links in the storefront and administration must include a meaningful "alt tag" or the original alt tag from the media manager.
-
-### Do not use `<hX>`-Tags
-
-The utilization of `<hX>`-tags in the storefront templates, which are set to `<meta name="robots" content="index,follow">`, is not permissible, as these tags are reserved exclusively for content purposes.
-However, you may employ `<span class="h2">`, for instance.
-
-### Do not use inline-css in the storefront templates
-
-Use your own classes and let your CSS be compiled by the plugin.
-
-[Add SCSS variables](../../../../../guides/plugins/plugins/storefront/add-scss-variables.md#add-scss-variables)
-
-### Prevent `!important` usage
-
-Please avoid using the `!important` rule whenever possible.
-
-[Add SCSS variables](../../../../../guides/plugins/plugins/storefront/add-scss-variables.md#add-scss-variables)
-
-### New controller URLs / XHR requests
-
-We check for new XHR/Document requests in the storefront as they must be accompanied by an `X-Robots-Tag` in the header request with the directive "noindex, nofollow.".
-For further details, please refer to the [robots meta tag](https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag?hl=de#xrobotstag) article.
-
-If the app creates its own controller URLs set to "index, follow" and the URLs are accessible via the frontend, then these "app URLs" must also appear in the `sitemap.xml`.
-In addition, these pages must include a valid canonical tag, their own meta description, and a title tag, which can be entered individually via the administration or as a text snippet.
-
-### Lighthouse A/B-Testing
-
-Could you do an A/B test with *Lighthouse Audit* to check the performance and quality of your frontend app?
-There should not be any drastic change in performance, accessibility values, or any new errors when activating the app.
-
-* **Testing tool** for A/B-Testing:
- * Link: [Google Lighthouse](https://developer.chrome.com/docs/lighthouse)
-
-### schema.org/Rich Snippets A/B-Testing
-
-Do an A/B-Test with *Scheme.org's Structured Data Testing Tool* and *Google Rich Result Tester* to check the homepage, categories, and various product detail pages (incl. available products, unavailable products, products with no review, single review, many reviews with various ratings, out-of-stock products, products to be released in the future or any other kind of product configuration and products including ean, mpn, width, length, height, weight).
-Also, could you check for duplicate entries as well as any new bugs?
-
-* **Testing tool** for A/B-Testing:
- * Link: [Schema Markup Validator of schema.org](https://validator.schema.org/)
- * Link: [Google Rich Result Tester](https://search.google.com/test/rich-results)
-
-### Usage of fonts from external sources
-
-If you are using external fonts (e.g., Google fonts, Fontawesome) or external services, the app store description must contain this information.
-
-Please be aware that you might have to edit your *data protection information*.
-This info could be placed as a tooltip near the font settings of the app configuration.
-
-### Register your cookie to the Cookie Consent Manager
-
-We expect every cookie set from the store URL to be optional and not technically required for running shopware.
-Therefore, the cookies had to be [registered in our Cookie Consent Manager](../../../../../guides/plugins/plugins/storefront/add-cookie-to-manager).
-
-We differentiate between "Technically required", "Marketing" and "Comfort features".
-All cookies must appear (unchecked) in the cookie configuration box in the frontend.
-
-## Administration guidelines
-
-### Menu entries in the main menu are not allowed
-
-Menu entries in the main menu of the administration are not allowed because of the look and feel.
-
-### Own media folder
-
-Manufacturer must create their own media folders with the right thumbnail settings or use existing ones to upload images, except for upload fields within the `config.xml`.
-
-If you use your own media folder, keep in mind that the folder and the included data had to be removed if selected during the uninstallation.
-
-### API test button
-
-* If your API corresponds via API credentials to external services, we expect an API test button.
-Apart from that, you can validate the required credentials while saving them in the app settings.
-In this case, a status message must be displayed in the administration and Shopware log.
-If the API data is incorrect, an entry must appear in the event log file in the Shopware folder `/var/log/` respectively in the database.
-
-* **Example** for implementing an API Test Button into the System Config form:
- * Link: [GitHub](https://github.com/shyim/ShyimApiTest)
-
-### Shopping experiences
-
-[Shopping worlds elements](../../../../../concepts/commerce/content/shopping-experiences-cms.md#elements) must include an element icon.
-If the app is deleted, *Shopping Worlds* should work flawlessly in the frontend.
-
-### Themes
-
-[Themes](../../../../../guides/plugins/themes/) must include its own preview image.
-
-### External technology/ Shopware Technology Partner (STP) apps
-
-Every external technology app needs to track its commission.
-Below is an example of implementing the tracking logic in their extensions:
-
-// POST /shopwarepartners/reports/technology - Allows partners to send us the info based on the STP contract
-
-```json
- {
- "identifier": "8e167662-6bbb-11eb-9439-0242ac130002",
- "reportDate": "2005-08-15T15:52:01",
- "instanceId": "alur24esfaw3ghk",
- "shopwareVersion": "6.3.1",
- "reportDataKeys": [
- {
- "customer": 3
- },
- {
- "turnover": 440
- }
- ]
- }
-```
-
-### Automatic code reviews with PhpStan and SonarQube
-
-Our most current code review configurations when uploading apps via the Shopware Account can be found on GitHub.
-
-* Link: [Code reviews for Shopware 6 on GitHub](https://github.com/shopwareLabs/store-plugin-codereview)
-
-### Sonarcube Rules status Blocker
-
-The following statements will be blocked as of 1st Oct. 2022:
--die; exit; var_dump
-
-* Link: [Refer to the list of the already existing blockers](https://s3.eu-central-1.amazonaws.com/wiki-assets.shopware.com/1657519735/blocker.txt).
-
-### Automated code tests with Cypress
-
-There are Cypress tests for Shopware 6 on GitHub.
-The project is driven by the *Friends of Shopware* group. You can contribute at any time:
-
-* Link: [Developer Documentation Cypress Tests for Shopware 6](../../../../../guides/plugins/plugins/testing/end-to-end-testing/)
-* Link: [Cypress Tests for Shopware 6](https://github.com/shopware/shopware/tree/trunk/src/Administration/Resources)
-
-### Useful tool for plugin development and extension management
-
-The [`shopware-cli`](https://github.com/shopware/shopware-cli) is a useful tool for building, validating and uploading new Shopware 6 plugin releases to the Community Store. It also allows you to manage the store description and images of your plugins efficiently.
-
-## Automatic code review - Errors
-
-### The required composer.json file was not found
-
-**Cause:** Error in composer.json
-
-One possible cause is that the technical app name from the Community Store or Account does not match the technical name entered in composer.json, or the app is incorrectly zipped.
-The technical app name must be stored in the composer.json, located at `composer.json` > extra > `shopware-plugin-class`.
-Could you take a look at the bootstrap class? Most of the errors are caused by the wrong technical name.
-For example, "Swag\\MyPlugin\\SwagMyPluginSW6" instead of "Swag\\MyPlugin\\SwagMyPlugin".
-
-Link: [Example of a valid composer.json](https://github.com/FriendsOfShopware/FroshPlatformPerformance/blob/master/composer.json#L20).
-
-### Ensure cross-domain messages are sent to the intended domain
-
-When using `postMessage()` or similar cross-window messaging APIs, verify the message origin (e.g. `event.origin`) and restrict target domains to trusted URLs instead of `'*'`. This prevents malicious sites from sending or receiving unauthorized messages.
-
-### No bootstrapping file found. Expecting bootstrapping in
-
-The bootstrap cannot be found.
-The reasons could be that the folder structure in the ZIP file needs to be corrected, a typo, or a case-sensitive error in the app source (e.g., in the technical name).
-
-### Class Shopware\Storefront\* not found
-
-Missing requirements in the composer.json (e.g. "require": {"shopware/frontend": "*"},)
-
-Link: "[Shopware App Development: App Meta Information - Explanation of the properties](../../../../../guides/plugins/plugins/plugin-base-guide#the-composerjson-file)
-
-### Cookies are written safely
-
-Be sure you set cookies as secure.
-Remember to register your cookie to the *Cookie Consent Manager*.
-
-### Call to static method jsonEncode() on an unknown class
-
-Shopware always uses json_Encode exclusively - there is no other fallback.
-
-### The lock file is not up to date with the latest changes in composer.json
-
-You may need to get updated dependencies. Run an update to update them.
-
-The `composer.lock` in the app archive has to be deleted.
-
-### Class Shopware\Core\System\Snippet\Files\SnippetFileInterface not found and could not be autoloaded
-
-In the Shopware 6 Early Access (EA) version, the mentioned class did not exist.
-Therefore, the code review failed. The reason for the problem is the following specification in the composer.json:
-
-```xml
-
-<pre>"require": {
-
- "shopware/core": "*",
-
- "shopware/storefront": "*"
-
-},</pre>
-```
-
-The Composer resolves this to "Whatever is the latest from these repositories" and then installs the Early Access version instead of the current Release Candidate.
-This happens because the Composer does not know an EA as a stability level (like stable or RC) and is, therefore, ultimately considered "stable".
-The solution is to amend the requirement as follows:
-
-```xml
-<pre>"require": {
-
- "shopware/core": "~6.1.0",
-
- "shopware/storefront": "~6.1.0"
-
-},
-
-"minimum-stability": "RC"</pre>
-```
-
-This ensures that at least version Shopware 6.1 is installed, even if it is a Release Candidate.
-It will be preferred as soon as the final 6.1 is released.
-
-### Remove out-commented code from your source-code
-
-### Unauthorized file formats or folders detected in the app
-
-Remove out-commented code, unused files and folders, and all dev-files from your binary.
-
-Here are some examples of not allowed folders and files:
-
-* ./tests
-* .DS_Store
-* .editorconfig
-* .eslintrc.js
-* .git
-* .github
-* .gitignore
-* .gitkeep
-* .gitlab-ci.yml
-* .gitpod.Dockerfile
-* .gitpod.yml
-* .phar
-* .php-cs-fixer.cache
-* .php-cs-fixer.dist.php
-* .php_cs.cache
-* .php_cs.dist
-* .prettierrc
-* .stylelintrc
-* .stylelintrc.js
-* .sw-zip-blacklist
-* .tar
-* .tar.gz
-* .travis.yml
-* .zip
-* .zipignore
-* ISSUE_TEMPLATE.md
-* Makefile
-* Thumbs.db
-* __MACOSX
-* auth.json
-* bitbucket-pipelines.yml
-* build.sh
-* composer.lock
-* eslint.config.js
-* grumphp.yml
-* package-lock.json
-* package.json
-* phpdoc.dist.xml
-* phpstan-baseline.neon
-* phpstan.neon
-* phpstan.neon.dist
-* phpunit.sh
-* phpunit.xml.dist
-* phpunitx.xml
-* psalm.xml
-* rector.php
-* shell.nix
-* stylelint.config.js
-* webpack.config.js