Scenario
On this page
A scenario is a set of steps.
Creating scenarios allow you to use them in one line instead of duplicate each steps that it contains.
#Creating scenario
You need to extends the Scenario class and add the steps() method.
1use PrestaFlow\Library\Scenarios\Scenario;2 3class AddProductToCart extends Scenario4{5 public function steps($testSuite)6 {7 return $testSuite;8 }9}
You can now write your steps as you will do inside a test suite.
1public function steps($testSuite) 2{ 3 $testSuite->importPage('FrontOffice\Category'); 4 $testSuite->importPage('FrontOffice\Product'); 5 6 extract($testSuite->pages); 7 8 $testSuite 9 ->it('go to category page', function () use ($frontOfficeCategoryPage) {10 $frontOfficeCategoryPage->goToPage('category', (int) $this->getParam('categoryId'));11 12 Expect::that($frontOfficeCategoryPage->getListingTitle())->contains($this->getParam('categoryTitle'));13 })14 ->it('go to product page', function () use ($frontOfficeCategoryPage, $frontOfficeProductPage) {15 $frontOfficeCategoryPage->goToProduct((int) $this->getParam('productIndex'));16 17 Expect::that($frontOfficeProductPage->getTitle())->contains($this->getParam('productTitle'));18 })19 ->it('add to cart', function () use ($frontOfficeProductPage) {20 $textResult = $frontOfficeProductPage->addToCart((int) $this->getParam('cartQuantity'));21 22 Expect::that($textResult)->contains($frontOfficeProductPage->message('addedToCart'));23 });24 25 return $testSuite;26}
#Use
1->scenario(ModuleCustom::class)
#Parameters
A scenario is a make to re-use steps.
As each steps could be taking one or more parameters distinctly, you can add a array of parameters.
#Declare parameters
1public $params = [2 'categoryId' => 3,3 'categoryTitle' => 'Vêtements',4 'productIndex' => 1,5 'productTitle' => 'T-shirt imprimé colibri',6 'cartQuantity' => 1,7];
You will define the key as a parameter and you can attach it a default value.
#Pass parameters in test suite
1->scenario(ModuleCustom::class, [2 'locale' => 'en',3 'useIsoCode' => true,4])
#Composing several scenarios in one suite
A suite can chain scenarios. State is shared between them via store() /
retrieve() on the suite, so a scenario can consume what a previous one produced
(for example, an order reference).
1$this2->describe('Create an order then manage its lifecycle in the BackOffice')3->scenario(\PrestaFlow\Library\Scenarios\CheckoutOrder::class)4->scenario(\PrestaFlow\Library\Scenarios\ManageOrder::class);
#Ready-to-use scenarios
Since v1.5.0, the library ships a set of end-to-end scenarios you can drop into a suite as-is or subclass to customise. Each of them is validated live against a PrestaShop 9 shop.
#CheckoutOrder
Logs in a customer on the FrontOffice, adds a product to the cart, goes through the full checkout tunnel, then verifies the order exists in the BackOffice.
On PrestaShop 9.2 and above it first makes sure the shop is on the four-page checkout, because the layout is a shop-wide setting another scenario may have switched (see Checkout layout below). That step signs in to the BackOffice, so this scenario needs valid BackOffice credentials even though the rest of it never leaves the FrontOffice.
Parameters
1public $params = [2 'locale' => 'fr',3 'customerEmail' => 'pub@prestashop.com',4 'customerPassword' => 'PrestaFlow2026!',5 'productUrl' => '1-1-hummingbird-printed-t-shirt.html',6 'cartQuantity' => 1,7];
Usage
1$this2->describe('Place an order end-to-end and verify it in the BackOffice')3->scenario(\PrestaFlow\Library\Scenarios\CheckoutOrder::class);
The scenario stores the order reference in the suite (store('orderReference')),
so a following scenario in the same suite can retrieve it.
#GuestCheckout
Same tunnel, but as a pure guest — the scenario fills the personal-information step (email + name), enters a new shipping address, and reaches the FrontOffice confirmation.
Like CheckoutOrder, it sets the four-page layout first on 9.2+, and therefore
needs BackOffice credentials.
Parameters
1public $params = [ 2 'locale' => 'fr', 3 'productUrl' => '1-1-hummingbird-printed-t-shirt.html', 4 'cartQuantity' => 1, 5 'guestEmail' => 'pf-guest@example.com', 6 'firstName' => 'PrestaFlow', 7 'lastName' => 'Guest', 8 'addressStreet' => '16 Main street', 9 'addressCity' => 'Paris',10 'addressPostcode' => '75002',11 'addressCountry' => 'France',12 'addressPhone' => '0102030405',13];
#ManageOrder
Opens an order in the BackOffice, changes its status, adds an internal note and
sets a tracking number — each action verified. Reads the order reference stored
by a preceding CheckoutOrder (or accepts an explicit orderReference param).
Parameters
1public $params = [2 'locale' => 'fr',3 'orderStatus' => 'Payment accepted',4 'internalNote' => 'PrestaFlow internal note',5 'trackingNumber' => 'PF-TRACK-0001',6 'orderReference' => null, // defaults to retrieve('orderReference')7];
The orderStatus value must match the label as shown in the BackOffice status
dropdown (the BackOffice admin language, which may differ from the FrontOffice
locale).
#EditProduct
Self-cleaning scenario: creates a product, opens it from the list, changes its price, verifies the new price is persisted, then deletes the product.
Parameters
1public $params = [2 'productName' => 'PF Edit Test',3 'initialPrice' => 9.99,4 'newPrice' => 19.99,5 'quantity' => 10,6];
#CreateProductAndVerify
BackOffice product creation followed by a FrontOffice visibility check, then a delete. Reads the product's canonical FrontOffice URL from the BackOffice edit page (Preview link) so the check is independent of the shop's URL rewriting.
Parameters
1public $params = [2 'productName' => 'PrestaFlow Scenario Product',3 'productPrice' => 9.99,4 'productQuantity' => 10,5];
#AddProductToCart
The historical FrontOffice scenario: browse to a category, open a product, add it to the cart, assert the modal message.
1public $params = [2 'categoryId' => 3,3 'categoryTitle' => 'Vêtements',4 'productIndex' => 1,5 'productTitle' => 'T-shirt imprimé colibri',6 'cartQuantity' => 1,7];
#Registration
Creates a customer account from the FrontOffice registration form, ticks the required consent boxes, and verifies a session is open afterwards.
Parameters
1public $params = [2 'locale' => 'en',3 // null => a unique address is generated for this run4 'email' => null,5 'password' => 'PrestaFlow2026!',6 'firstName' => 'PrestaFlow',7 'lastName' => 'Tester',8];
The e-mail is unique per run by default, so the scenario really exercises
account creation every time. A fixed address would succeed once and then fail
on every later run against the same shop — or, worse, quietly stop testing
anything. Pass an explicit email to provision a known account instead, or use
EnsureTestAccount below, which wraps that case.
#EnsureTestAccount
Makes sure a known customer account exists, so scenarios that need a logged-in customer have credentials they can rely on.
Parameters
1public $params = [2 'locale' => 'en',3 // null => falls back to the FO_EMAIL / FO_PASSWD globals4 'email' => null,5 'password' => null,6 'firstName' => 'PrestaFlow',7 'lastName' => 'Fixture',8];
This is a provisioner, not a test. On a shop where the account already exists it deliberately creates nothing — which would make it a meaningless test, but is exactly right for a fixture. It stays honest by asserting the end state rather than the path it took: whichever branch runs, the scenario only passes if the credentials actually open a session.
Credentials default to PRESTAFLOW_FO_EMAIL / PRESTAFLOW_FO_PASSWD, so no
password is hardcoded.
#OnePageCheckoutOrder
Places an order through the One Page Checkout as a logged-in customer.
PrestaShop 9.2 ships the One Page Checkout as the ps_onepagecheckout module,
off by default. The scenario switches the shop to the one-page layout in the
BackOffice before touching the FrontOffice. Below 9.2 it skips with an
explicit message rather than failing later on a selector that cannot exist.
Parameters
1public $params = [ 2 'locale' => 'en', 3 // null => falls back to the FO_EMAIL / FO_PASSWD globals 4 'customerEmail' => null, 5 'customerPassword' => null, 6 'productUrl' => '6-mug-the-best-is-yet-to-come.html', 7 'cartQuantity' => 1, 8 // used only when the customer has no saved address yet 9 'firstName' => 'PrestaFlow',10 'lastName' => 'Fixture',11 'addressStreet' => '16 Main street',12 'addressCity' => 'Paris',13 'addressPostcode' => '75002',14 'addressCountry' => 'France',15 'addressPhone' => '0102030405',16];
productUrl points at a product without combinations on purpose: adding one
to the cart then needs no id_product_attribute, unlike the demo t-shirt.
#OnePageCheckoutGuest
The same One Page Checkout, as a guest. It also enables guest checkout
(PS_GUEST_CHECKOUT_ENABLED) in Shop Parameters, since that setting lives
elsewhere than the checkout layout.
Parameters
1public $params = [ 2 'locale' => 'en', 3 'guestEmail' => 'pf-opc-guest@example.com', 4 'firstName' => 'PrestaFlow', 5 'lastName' => 'Guest', 6 'addressStreet' => '16 Main street', 7 'addressCity' => 'Paris', 8 'addressPostcode' => '75002', 9 'addressCountry' => 'France',10 'addressPhone' => '0102030405',11 'productUrl' => '6-mug-the-best-is-yet-to-come.html',12 'cartQuantity' => 1,13];
#SwitchTheme
Puts the shop on a given front-office theme, through Design > Theme & Logo.
Parameters
1public $params = [2 'locale' => 'en',3 // null => the theme the suite is already configured for (PRESTAFLOW_THEME)4 'theme' => null,5 'shopId' => 1,6];
A fixture more than a test, like EnsureTestAccount: it guarantees the end
state, so a shop already on the right theme is a legitimate pass.
Use it when a suite depends on theme selectors
being right. Writing ps_shop.theme_name straight into the database changes the
name and nothing else — no hooks replayed, no module registrations — so a suite
"validated" that way proves less than it appears to.
Two things worth knowing before you script around it:
- The Use this theme button is rendered
disabledoutside a single-shop context, so the scenario sets that context first. On a multistore the page otherwise looks perfectly normal while the button does nothing. - Applying a theme invalidates PrestaShop's Symfony container cache, and the next back-office request can answer HTTP 500 while it rebuilds. The scenario re-opens the page until it comes back, so its assertion judges the theme and not the cache. A suite that chains straight into another back-office page after a switch should expect the same hiccup.
#Checkout layout
From 9.2, a shop is either on the four-page tunnel or on the One Page Checkout, and that is a shop-wide setting. It matters for scenarios because the two render completely different markup.
The rule the shipped scenarios follow is: each scenario sets the state it needs, and none of them restores anything afterwards.
Restoring sounds tidier, but it buys nothing — a run that dies halfway restores nothing anyway — and it makes every scenario pay for a cleanup that the next one will immediately undo. Setting the state up front is what makes the scenarios independent of the order they run in.
So the One Page Checkout scenarios switch the layout on and leave it on, and
CheckoutOrder and GuestCheckout switch it off and leave it off. Whichever
runs last wins, and it does not matter.
If you write your own scenario that drives FrontOffice\Checkout, call the
precondition first:
1public function steps($testSuite)2{3 $this->requireFourPageCheckout($testSuite);4 5 // ... your steps6}
It does nothing below 9.2, where no module owns the setting, and it only clicks when the shop is actually on the wrong layout.
Skipping it is the kind of mistake that does not announce itself: the One Page
Checkout renders its own markup, the four-page selectors match nothing, and a
missing selector makes click() return false rather than raise — so the
scenario reports passing steps while filling a form that is not on screen.