pql-test — DAX Test Runner for PBIP Models

Run Your Semantic Model Tests from the Command Line

pql-test is a command-line tool that discovers and executes the DAX tests stored inside your Power BI Project (PBIP) semantic models, connecting to Analysis Services over XMLA. Tests live as .dax files alongside your model and are written with the PQL.Assert function family.

Where PQL.Assert gives you the assertions that live inside the model, pql-test is the automation half: it runs those assertions against a local Power BI Desktop session or a deployed Power BI Premium or Microsoft Fabric workspace, and reports the results in a form your terminal and your pipeline can both read.

---

Table of Contents

• pql-test — DAX Test Runner for PBIP Models
  • Table of Contents
  • Prerequisites
  • Installation
  • Distribution
    • 1. Install the build tool
    • 2. Build the wheel
    • 3. Install the wheel on another machine
    • 4. Distribution options
    • Updating the version
  • Model Path Formats
    • Filesystem path (default)
    • Local model name (local/<model_name>)
    • Fabric service path (<workspace>.Workspace/<model>.SemanticModel)
  • Example Models
    • SampleModel
    • RLS_Model (Row-Level Security)
    • OLS_Model (Object-Level Security)
  • PBIP Model Layout
  • Writing Test Files
    • Standard test schema (4 columns)
    • Best-practices test schema (5 columns)
    • Naming convention
  • Authentication
    • Quick Start
    • Authentication Methods
      • Interactive User Authentication
      • Service Principal with Secret
      • Service Principal with Certificate
      • Managed Identity (Azure VM/Container)
    • Credential Priority
    • Secure Storage
  • Commands
    • check-prereqs
    • retrieve-tests
    • retrieve-test
    • run-tests
    • code-coverage
  • Testing against ODCS data contracts
  • Connection Options
    • Local Power BI Desktop (auto-detected)
    • Remote Power BI Premium / Fabric Workspace
    • Sovereign / government clouds
  • Example Test Suites
    • Calculations
    • Data Quality
    • Schema
    • Best Practices
  • Exit Codes
  • Troubleshooting
    • pql-test is not recognised
    • Error: Model path not found
    • No tests found
    • No XMLA connection detected
    • msal not installed / pythonnet not installed
    • Failed to acquire access token
    • Query returned no rows
    • Cannot connect to XMLA endpoint

---

Prerequisites

The only thing you install manually is Python 3.10+ (python.org — check "Add python.exe to PATH" on Windows). Everything else is handled automatically:

Requirement	How it's installed
Python 3.10+	Manual — install from python.org and ensure it's on PATH
pythonnet, msal, azure-identity, keyring, click, python-dotenv, psutil	Automatic via pip — pulled in as Python dependencies when you pip install pql-test
ADOMD.NET assemblies (the .NET XMLA client)	Automatic on first use — when no ADOMD.NET install is detected, pql-test downloads the official Microsoft.AnalysisServices.AdomdClient NuGet package (~5 MB) from nuget.org to %USERPROFILE%\.pql-test\adomd\ and uses it for every subsequent run. No admin rights, no manual MSI. Set PQL_TEST_NO_AUTO_INSTALL_ADOMD=1 if you'd rather provide ADOMD yourself.
Power BI Desktop (optional)	Only needed for local/<model_name> mode against a locally-open model. Skip if you only target the service.

Windows or Linux. Commands that query a model over XMLA (run-tests, code-coverage, contract run, and doctor's live checks) need ADOMD.NET, which runs on Windows only; elsewhere they stop with one message saying so. The file-based commands also run on Linux, for example in a CI pipeline: retrieve-tests and retrieve-test with a PBIP folder, and contract lint|coverage|generate|trace.

Run the built-in check to verify your environment (this is also when the one-time ADOMD download will fire, if needed):

pql-test check-prereqs

---

This is the beginning of the README. Read the rest at the original. Read the full README ↗