areopa.academy

What about Page Scripting? An Introduction and Beyond

—

by

blog inserter
in

In this 96th Areopa Academy webinar, Microsoft MVPs Bert Verbeek and Luc van Vugt — both senior technical specialists at 4PS — take a deep dive into the Page Scripting feature introduced in Business Central 2024 Wave 1 (BC24). Moderator Henrik Helgesen guides the session from basic recording through advanced pipeline automation, AI-assisted BCPT scenario generation, and an honest look at current limitations. The webinar runs just under an hour and covers everything from first-time setup to converting YAML recordings into performance test cases.

What Is Page Scripting?

Page Scripting is a built-in tool in the Business Central web client that lets users record their interactions with the UI — opening pages, clicking actions, filling in fields — and then replay those interactions automatically. The primary target is user acceptance testing (UAT): verifying that business processes continue to work correctly after application updates or customization changes.

Recordings are stored as YAML files, which can be exported, shared via a URL link, or imported into another environment. Because the tool captures AL code execution rather than raw HTML, it is specific to the Business Central client and cannot automate control add-ins, embedded Power BI reports, or anything outside the BC web client.

📖 Docs: Use page scripting tool for acceptance testing (preview) — Microsoft Learn — official reference covering setup, recording steps, playback, YAML parameters, and pipeline integration.

Page Scripting vs. Test Automation

Bert drew a clear boundary between the two approaches. Page Scripting is aimed at end users and consultants and is best suited for validating longer, real-world workflows after implementation. AL test automation, by contrast, is a developer tool designed for continuous, unit-level testing that runs data-isolated scenarios before implementation is complete.

Key practical differences the presenters highlighted:

  • Data isolation: Page Scripting writes real records to the database; AL tests can (and should) clean up after themselves.
  • Speed: Page Scripting replays full UI flows and is noticeably slower than code-level tests.
  • Timing: Page Scripting is typically done after a feature is built; AL tests are ideally written before implementation begins.
  • Data requirements: Page Scripting usually requires existing data in the environment; AL tests can create their own test data programmatically.

Basic Features: Recording and Playback

Luc demonstrated the basic recording workflow live. You open the Page Scripting pane from the Settings gear in the top-right corner — but only if the correct permission set has been assigned. Two permission sets are relevant:

  • PAGESCRIPTING – REC — required to record.
  • PAGESCRIPTING – PLAY — required to replay. This is not included in the Dynamics 365 Basic permission set by default.

During recording, every action is captured as a step in the pane. When done, you can rewind and play back immediately, or save the recording to a YAML file. If you share the recording via the Copy Link button, the full script is embedded in the URL — note that the link does not include the company name, so recipients need to know which company to open separately.

Luc also demonstrated a practical tip: always start your recording from the Role Center. This ensures the playback has a consistent, known starting point. The script does not automatically navigate back to where you started — that navigation must be part of the recording itself.

📖 Docs: Recording steps — Microsoft Learn — covers how to start, pause, delete steps, insert steps mid-recording, and rearrange steps in the pane.

Advanced Features: YAML Editing and Includes

Bert walked through what the YAML recording file actually contains. The file has a header (with name, description, starting profile) and a list of step entries. Each step has a readable description field that explains what the step does in plain language, making the file approachable even for non-developers.

Two advanced capabilities that are only available by editing the YAML directly (not through the UI) are:

Parameters

You can define named parameters in the script header and reference them in input steps using Parameters.ParameterName syntax. This makes scripts reusable across different test data sets without having to re-record. The parameter name in the header must be lowercase — using a capitalized name causes the parameter not to be recognized.

parameters:
  customerDescription:
    type: string
    default: "Test Customer 1234"

Includes

A host script can include other YAML scripts as sub-steps. This allows you to build modular, composable test suites — for example, a “create customer” recording included by multiple higher-level scripts. Bert noted one current limitation: parameters defined in the host script header cannot be passed into included scripts. This has been flagged to Microsoft as a requested improvement.

When loading a script with includes in the browser, you must explicitly grant the browser access to the folder containing the included files, which can be slightly awkward but does work.

📖 Docs: Include other scripts — Microsoft Learn — explains how to compose recordings and pass parameters across included scripts.

Replay from the Command Line (BC25)

Business Central 2024 Wave 2 (BC25) added the ability to run page scripts from the command line via an npm package, enabling automation in CI/CD pipelines. Luc demonstrated this using a PowerShell script calling the package.

To install:

npm install -g @microsoft/bc-replay

To run all scripts in a folder:

npx replay .\recordings\*.yml `
  -StartAddress http://localhost:8080/bc250/ `
  -Authentication UserPassword `
  -UserNameKey BC_USER `
  -PasswordKey BC_PASS `
  -ResultDir c:\bc-replay\results

The tool is built on top of Playwright and opens a real browser session to execute the script. Results are written to a Playwright HTML report that includes a step-by-step replay recording — useful for diagnosing failures. Multiple YAML files in a folder run concurrently using Playwright workers.

Important constraints at the time of the webinar:

  • You can specify a start URL but not a company name — the tool uses the last company opened by the authenticated user.
  • Accounts with multi-factor authentication (MFA) are not supported; use a dedicated test account with username/password only.
  • Azure Active Directory authentication was working for Sandbox environments but with some limitations — always test before relying on it in a pipeline.
📖 Docs: Run page scripts in pipelines — Microsoft Learn — full syntax reference for npx replay including all parameters.

Converting Recordings to BCPT Scenarios with AI

Bert demonstrated how a Page Scripting YAML file can be used as input to an AI model (such as Azure OpenAI / ChatGPT) to generate a starting point for a BC Performance Toolkit (BCPT) scenario in AL.

The Business Central Performance Toolkit is a separate extension available from AppSource that lets developers define test scenarios running in parallel to simulate concurrent user load — up to 500 parallel sessions via PowerShell. Traditionally, writing BCPT scenarios in AL is the most time-consuming part of performance testing.

The workflow Bert demonstrated:

  1. A consultant records a business scenario using the Page Scripting tool (no AL knowledge required).
  2. The saved YAML file is pasted into an AI prompt along with a system prompt that describes the BCPT scenario structure.
  3. The AI generates AL code for the BCPT scenario, which the developer then reviews and adjusts.

Bert’s system prompt and example files are available on his GitHub repository — see Create your BCPT scenarios with page scripting and AI on his blog for context and the GitHub link.

📖 Docs: The Performance Toolkit extension — Microsoft Learn — full reference for BCPT, including how to define and run test suites and analyze results in Power BI.

Generating User Manuals from Recordings

Luc showed a second creative use case: converting a Page Scripting YAML file into a user manual using the Central Queue AppSource extension built by Dmitri Katson. The extension adds a chat interface inside Business Central backed by an AI model. You can upload your YAML script, ask it to generate step-by-step work instructions, and then export the result as a Word document or Markdown file. Luc noted that you should obtain a license for the AppSource app before installing it.

Best Practices

The presenters distilled the following guidance from their own experience and Microsoft’s documentation:

  • Start from the Role Center. This ensures the script always begins from a consistent, known state — especially important when running from the command line.
  • Use ISO date format (YYYY-MM-DD). Hardcoded dates in regional format (DD/MM/YYYY or MM/DD/YYYY) will fail when the script is run by a user with different regional settings. Use year-first format always.
  • Type lookup values instead of selecting from a dropdown. Dropdown selections record the row number, not the record key. If the list order changes (e.g., after installing an extension that adds items to an enum), the script will select the wrong record.
  • Filter list pages before selecting. Navigate to the specific record by filtering rather than scrolling — the script will be more robust across data changes.
  • Break recordings into small, reusable parts. Use the includes feature to compose modular scripts — for example, a dedicated “setup customer” recording that can be included by multiple test suites.
  • Create new entities in tests where possible. Avoid depending on pre-existing data that may not be present in every environment.

Current Constraints (as of BC24/BC25)

Page Scripting is still in preview. Bert and Luc compiled the following known limitations:

  • Editing steps is limited in the UI — you can delete the last step while recording and change values in existing steps, but you cannot reorder or insert arbitrary steps without editing the YAML.
  • Control add-ins, embedded Power BI reports, and anything outside the BC web client cannot be automated.
  • Personalizations applied by the user are not captured by the recording.
  • Dropdown selections record row position, not record key — vulnerable to list changes.
  • The date picker control cannot be recorded.
  • Multi-line selection (e.g., Ctrl+A on a list) is not recorded — only the last selected line is captured.
  • The command-line replay tool (npx replay) cannot target a specific company by name.
  • Report preview pages cannot be closed by the recording — report generation must be the final step.
  • In-app notifications and error dialogs are captured but cannot be replayed.
  • The Next/Previous navigation buttons on card pages are not handled.
  • Fields with the same name on different pages may be confused during playback.
  • Includes require HTTPS — running against a non-SSL Docker container will cause include loading to fail.

The Future of Page Scripting

Luc shared a slide showing items on Microsoft’s internal consideration list for Page Scripting. While Microsoft made no formal commitments, the areas discussed include: automatic navigation to the recording’s starting point, better test script management and versioning, AI-assisted AL test code generation from YAML recordings, support for producing e-learning content from recordings, and environment validation scripts. The audience was encouraged to submit feedback directly to Microsoft using the survey link shared by the presenters.

Resources

This post was drafted with AI assistance based on the webinar transcript and video content.