Scenario


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.

Copied!
1use PrestaFlow\Library\Scenarios\Scenario;
2 
3class AddProductToCart extends Scenario
4{
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.

Copied!
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

Copied!
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

Copied!
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

Copied!
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).

Copied!
1$this
2->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

Copied!
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

Copied!
1$this
2->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

Copied!
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

Copied!
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

Copied!
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

Copied!
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.

Copied!
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

Copied!
1public $params = [
2 'locale' => 'en',
3 // null => a unique address is generated for this run
4 '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

Copied!
1public $params = [
2 'locale' => 'en',
3 // null => falls back to the FO_EMAIL / FO_PASSWD globals
4 '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

Copied!
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

Copied!
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

Copied!
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 disabled outside 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:

Copied!
1public function steps($testSuite)
2{
3 $this->requireFourPageCheckout($testSuite);
4 
5 // ... your steps
6}

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.