@shopware-ag/acceptance-test-suite 11.15.2 → 11.15.3

package/README.md

@@ -16,6 +16,7 @@ This test suite is an extension to [Playwright](https://playwright.dev/) to easi
 * [Data Fixtures](#data-fixtures)
 * [Test Data Service](#test-data-service)
 * [Code Contribution](#code-contribution)
+* [Local Development with ATS](#local-development-with-ats)
 * [Best practices](#best-practices)
 * [Running Tests in the Test Suite](#running-tests-in-the-test-suite)
 
@@ -72,6 +73,33 @@ export default defineConfig({
 
 For more information about how to configure your Playwright project, have a look into the [official documentation](https://playwright.dev/docs/test-configuration).
 
+### Mailpit Configuration
+Set up your local Mailpit instance by following the instructions at [Mailpit GitHub repository](https://github.com/axllent/mailpit).  
+By default, Mailpit starts a web interface at `http://localhost:8025` and listens for SMTP on port `1025`.  
+Set the `MAILPIT_BASE_URL` environment variable in `playwright.config.ts` to `http://localhost:8025`. You can now run email tests, such as `tests/Mailpit.spec.ts`.
+
+## Testing With ATS
+The `tests` folder ensures the reliability of the testing framework by validating the functionality of tools and data used in tests. Add tests to verify any new features or changes you introduce:
+
+- **Page Objects**: Ensure they are correctly implemented and interact with the application as expected, including navigation, element visibility, and user interactions.
+- **TestDataService Methods**: Verify that methods for creating, getting, and cleaning up test data (e.g., products, customers, orders) work correctly and produce consistent results.
+
+```TypeScript
+//Example for page objects
+
+await ShopAdmin.goesTo(AdminManufacturerCreate.url());
+await ShopAdmin.expects(AdminManufacturerCreate.nameInput).toBeVisible();
+await ShopAdmin.expects(AdminManufacturerCreate.saveButton).toBeVisible();
+```
+
+```TypeScript
+//Example for TestDataService
+
+const product = await TestDataService.createProductWithImage({ description: 'Test Description' });
+expect(product.description).toEqual('Test Description');
+expect(product.coverId).toBeDefined();
+```
+
 ## Usage
 The test suite uses the [extension system](https://playwright.dev/docs/extensibility) of Playwright and can be used as a full drop-in for Playwright. But, as you might also want to add your own extensions, the best way to use it is to create your own base test file and use it as the central reference for your test files. Add it to your project root or a specific fixture directory and name it whatever you like.
 
@@ -206,6 +234,9 @@ Note that this is just a very rough example. In most cases you won't use this pa
 ### StorefrontPage
 This fixture provides a Playwright [page](https://playwright.dev/docs/api/class-page) context for the Shopware Storefront of the default sales channel.
 
+### Add new fixtures
+To add new general fixtures create them inside the `src/fixtures` folder. Keep in mind, that you need to merge your new fixture inside the `/src/index.ts` file.
+
 ## Page Objects
 Page objects can be helpful to simplify the usage of element selectors and make them available in a reusable way. They help you to organize page specific locators and provide helpers for interacting with a given page. Within our test suite we try to keep the page objects very simple and not to add too much logic to them. So most of the page objects resemble just a collection of element locators and maybe some little helper methods.
 
@@ -224,6 +255,44 @@ test('Storefront cart test scenario', async ({ StorefrontPage, StorefrontCheckou
 
 You can get an overview of all available page objects in the [repository](https://github.com/shopware/acceptance-test-suite/tree/trunk/src/page-objects) of this test suite.
 
+## Page object module
+The `modules` folder is designed to house reusable utility functions that operate on a `Page` object (from Playwright). These functions dynamically interact with different browser pages or contexts using the `page` parameter.
+For example, utility functions like `getCustomFieldCardLocators` or `getSelectFieldListitem` are used across multiple page objects to handle specific functionality (e.g., managing custom fields or select field list items). Centralizing these utilities in the `modules` folder improves code organization, readability, and reduces duplication.
+Create a new class inside module when it helps to streamline the codebase and avoid repetitive logic across page objects.
+
+You can find how `getCustomFieldCardLocators` is defined in the [modules folder ](./src/page-objects/administration/modules/CustomFieldCard.ts) and used in other page object class [here](./src/page-objects/administration/ProductDetail.ts).
+
+### Add new Page Objects
+Page objects are organized mainly by their usage in the administration or storefront. To add a new page object just add it in the respective subfolder and reference it in the `AdministrationPages.ts` or `StorefrontPages.ts`.
+
+**Usage**  
+```TypeScript
+import { test as base } from '@playwright/test';
+import type { FixtureTypes } from '../types/FixtureTypes';
+
+import { ProductDetail } from './administration/ProductDetail';
+import { OrderDetail } from './administration/OrderDetail';
+import { CustomerListing } from './administration/CustomerListing';
+// [...]
+import { MyNewPage } from './administration/MyNewPage';
+
+export interface AdministrationPageTypes {
+    AdminProductDetail: ProductDetail;
+    AdminOrderDetail: OrderDetail;
+    AdminCustomerListing: CustomerListing;
+    // [...]
+    AdminMyNewPage: MyNewPage;
+}
+
+export const AdminPageObjects = {
+    ProductDetail,
+    OrderDetail,
+    CustomerListing,
+    // [...]
+    MyNewPage,
+}
+```
+
 ## Actor Pattern
 The actor pattern is a very simple concept that we added to our test suite. It is something that is not related to Playwright, but similar concepts exist in other testing frameworks. We implemented it, because we want to have reusable test logic that can be used in a human-readable form, without abstracting away Playwright as a framework. So you are totally free to use it or not. Any normal Playwright functionality will still be usable in your tests.
 
@@ -320,7 +389,7 @@ test('Customer login test scenario', async ({ ShopCustomer, Login }) => {
 });
 ```
 
-You can create your own tasks in the same way to make them available for the actor pattern. Every task is just a simple Playwright fixture containing a function call with the corresponding test logic. Make sure to merge your task fixtures with other fixtures you created in your base test file. You can use the `mergeTests` method of Playwright to combine several fixtures into one test extension.
+You can create your own tasks in the same way to make them available for the actor pattern. Every task is just a simple Playwright fixture containing a function call with the corresponding test logic. Make sure to merge your task fixtures with other fixtures you created in your base test file. You can use the `mergeTests` method of Playwright to combine several fixtures into one test extension. Use `/src/tasks/shop-customer-tasks.ts` or `/src/tasks/shop-admin-tasks.ts` for that.
 
 ## Data Fixtures
 
@@ -439,6 +508,37 @@ You can contribute to this project via its [official repository](https://github.
 
 This project uses [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/). Please make sure to form your commits accordingly to the spec.
 
+## Local Development with ATS
+To work locally with the Acceptance Test Suite (ATS) and your development setup, follow these steps:
+
+### Create Your Page Objects and TestDataService Methods
+
+In the ATS repository (shopware/acceptance-test-suite), create or modify your custom page objects, TestDataService methods, or any related files.
+
+After making your changes, build the project by running the following command in the ATS repository:
+```bash
+npm run build
+```
+This will generate the necessary artifacts in the dist folder.
+
+Copy the generated artifacts (e.g., all files in the dist folder) from the ATS repository to your local Shopware instance's `node_modules` folder, specifically under the ATS package path:
+```bash
+cp -R dist/* <path-to-your-shopware-instance>/tests/acceptance/node_modules/@shopware-ag/acceptance-test-suite/dist
+````
+### Adjust Tests, Page Objects, and Methods
+
+In your Shopware instance, adjust any tests, page objects, TestDataService methods, or other related files to align them with the changes made in the ATS repository.
+
+### Run the Tests
+
+Execute the tests to verify your changes. Use the following command from your Shopware project's acceptance test directory:
+```bash
+cd tests/acceptance
+npx playwright test --ui
+```
+This will launch the Playwright Test Runner UI where you can select and run specific tests.
+By following these steps, you can work locally with the ATS and test your changes in your Shopware instance.
+
 ## Best practices
 
 A good first read about this is the official [playwright best practices page](https://playwright.dev/docs/best-practices). It describes the most important practices which should also be followed when writing acceptance tests for Shopware.

package/dist/index.d.mts

@@ -1875,6 +1875,7 @@ declare class OrderDetail implements PageObject {
     readonly saveButton: Locator;
     readonly dataGridContextButton: Locator;
     readonly orderTag: Locator;
+    readonly itemsCardHeader: Locator;
     constructor(page: Page, instanceMeta: HelperFixtureTypes['InstanceMeta']);
     url(orderId: string, tabName?: string): string;
     getCustomFieldCardLocators(customFieldSetName: string, customFieldTextName: string): Promise<{

package/dist/index.d.ts

@@ -1875,6 +1875,7 @@ declare class OrderDetail implements PageObject {
     readonly saveButton: Locator;
     readonly dataGridContextButton: Locator;
     readonly orderTag: Locator;
+    readonly itemsCardHeader: Locator;
     constructor(page: Page, instanceMeta: HelperFixtureTypes['InstanceMeta']);
     url(orderId: string, tabName?: string): string;
     getCustomFieldCardLocators(customFieldSetName: string, customFieldTextName: string): Promise<{

package/dist/index.mjs

@@ -4866,9 +4866,15 @@ class OrderDetail {
     __publicField$v(this, "saveButton");
     __publicField$v(this, "dataGridContextButton");
     __publicField$v(this, "orderTag");
+    __publicField$v(this, "itemsCardHeader");
     this.saveButton = page.locator(".sw-order-detail__smart-bar-save-button");
     this.dataGridContextButton = page.locator(".sw-data-grid__actions-menu").and(page.getByRole("button"));
     this.orderTag = page.locator(".sw-select-selection-list__item");
+    if (satisfies(instanceMeta.version, "<6.7")) {
+      this.itemsCardHeader = page.locator(".sw-card__header").getByText("Items");
+    } else {
+      this.itemsCardHeader = page.locator(".mt-card__header").getByText("Items");
+    }
   }
   url(orderId, tabName = "general") {
     return `#/sw/order/detail/${orderId}/${tabName}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shopware-ag/acceptance-test-suite",
-  "version": "11.15.2",
+  "version": "11.15.3",
   "description": "Shopware Acceptance Test Suite",
   "author": "shopware AG",
   "license": "MIT",