typo3-steps

Cucumber step definitions for testing TYPO3 sites with webship-js — a BDD browser automation harness built on Playwright + Cucumber-js.

@webship-js/typo3-steps adds a typo3.steps.js step file plus .feature files that cover the main navigation (including the Bootstrap 5 "Content Examples" mega-menu dropdown and the collapsed mobile navbar), page headings, and the Bootstrap accordion content element of a TYPO3 install running the official typo3/cms-introduction demo content on the bk2k/bootstrap_package frontend theme.

Published to npmjs.com as @webship-js/typo3-steps.

The steps assume that theme's markup: #mainnavigation with a.nav-link-main links, the .nav-style-mega / .dropdown-menu-mega mega-menu dropdown, h1.carousel-header / h1.element-header page headings and the Bootstrap .accordion-item / .accordion-button accordion. A site on another theme needs those selectors adjusted. The reference features assert the Introduction demo's own paths, menu labels and copy ("Media Left", "short video", /content-examples/interactive/accordion, ...); that is deliberate for a demo install, so swap those values for your site's content when you copy a feature. The steps themselves carry no site data: every label, title and phrase is a capture group.

Requirements

• Node.js >= 20
• A webship-js 2.0 test project

Install

npm install --save-dev @webship-js/typo3-steps

Quick start

1. Add @webship-js/typo3-steps's step file to your webship-js cucumber.js require array:

   require: [
     'node_modules/webship-js/tests/step-definitions/**/*.js',
     'node_modules/@webship-js/typo3-steps/tests/step-definitions/typo3.steps.js',
     'tests/step-definitions/**/*.js',
   ],

2. Point launchUrl at your TYPO3 site:

   worldParameters: {
     launchUrl: process.env.LAUNCH_URL || 'https://your-typo3-site.example',
   },

3. Copy a feature file from tests/features/ into your project's tests/features/ directory and adjust the menu items / page titles to match your site's content.

4. Run the suite:

   npx cucumber-js

What's included

| Path | Purpose | | --- | --- | | tests/step-definitions/typo3.steps.js | TYPO3-specific Cucumber steps (main-menu navigation, mobile navbar, mega-menu dropdown, page-heading assertion, accordion content element). | | tests/features/*.feature | Feature files exercising the steps against a locally DDEV-built typo3/cms-introduction site, desktop + mobile — see tests/features/README.md. | | .github/workflows/test.yml | CI: builds a default TYPO3 site with DDEV, then runs the dry-run + full suite against it on every push/PR. |

Step catalogue (summary)

| Step | Type | | --- | --- | | I open the "<name>" menu item | When | | I should( not) see the "<name>" menu item | Then | | I open the (content examples )mega menu | When | | I open the "<name>" dropdown link | When | | I should( not) see the "<name>" dropdown link | Then | | I should( not) be viewing the "<title>" page | Then | | I open the "<label>" accordion panel | When | | I should( not) see "<phrase>" in the "<label>" accordion panel | Then |

Every Then step takes should or should not, every step takes I, we or no pronoun, and every failure is a friendly message with a hint (no Playwright stack). Assertions wait on their locator for the minWaitTime.page budget (at least 10 s) instead of reading the page once. npm run test:examples checks that every Example #n: line in the step JSDoc matches its own step (and no webship-js core step) and that every feature step is defined exactly once; CI runs it before the dry run.

Full details and Gherkin examples for every step are documented inline in tests/step-definitions/typo3.steps.js and summarized in tests/step-definitions/README.md.

Running the tests in this repo

The CI workflow builds its own TYPO3 site with DDEV on every run (see .github/workflows/test.yml). To run the same suite locally:

npm install

# Build a TYPO3 v13 site with the introduction package via DDEV
mkdir .typo3-site && cd .typo3-site
ddev config --project-type=typo3 --docroot=public --php-version=8.3 --project-name=typo3-intro --auto
ddev start
ddev composer create-project "typo3/cms-base-distribution:^13" . --no-interaction
ddev typo3 setup --server-type=other --driver=mysqli --host=db --port=3306 \
  --dbname=db --username=db --password=db \
  --admin-username=admin --admin-user-password='Introduction!23' \
  --project-name="TYPO3 Introduction" --no-interaction --force
ddev composer require typo3/cms-introduction --no-interaction
# extension:setup activates the introduction package and auto-imports its
# demo content + site config — no separate import step needed.
ddev exec vendor/bin/typo3 extension:setup
ddev exec vendor/bin/typo3 cache:flush
cd ..

# Run the suite against the local DDEV site
LAUNCH_URL=https://typo3-intro.ddev.site npx cucumber-js

License

MIT — see LICENSE.