Last edit: Jun 24, 2022

This article describes how to use the End-To-End and unit tests included in the pOS Marketplace Template.


End-to-end testing is a best practice and a requirement if you would like to implement a maintainable platformOS end client build. Besides leveraging the test scripts included in the template, you can learn more about testing in our End-to-End Testing guides.

E2E Tests

Testcafe tests are located in the test/ directory.

To run tests:

1. Clean your Instance and seed test data:

It might not be necessary in many cases but some tests require a clean slate and will fail if previous content exists. You might need to clean all the data from your Instance by using:

pos-cli data clean [YOUR_ENV_NAME]

And after that seed the test data:

pos-cli data import --path=./seed/data.zip --zip [YOUR_ENV_NAME]

2. Set the environment variable

First, set the environment variable to point to your Instance.

On unix-based operating systems you can do this by prefixing all your commands with:


so your commands look like this:

MPKIT_URL=https://your-instance.example.com testcafe "chromium" test/ --debug-on-fail

On Windows you just set the variable once in PowerShell using:


3. Run tests

In headless mode, if you have Chromium installed:

testcafe "chromium:headless" test/

or just using Google Chrome:

testcafe "chrome" test/

4. Debug

To manually debug in case the test fails:

testcafe "chromium" test/ --debug-on-fail

To save screenshots of test fails:

testcafe "chromium" test/ -s takeOnFails=true

E2E Test Report

To make a test report as page (with screenshots):

MPKIT_URL=https://your-instance.example.com testcafe chrome:headless test/ report --reporter html:app/views/pages/_test_results/index.liquid -s path=test/screenshots/,takeOnFails=true

Then open your browser and you can visit it at:

Unit Tests

Put tests into app/views/partials/test/commands, files should end with _test.liquid.

To run all tests, deploy code on Instance and go to page:
To run one test go to page:

Use assertion partials from app/views/partials/test/assertions.

Example of unit test file with user creating/deleting:

In this example, you will assign json data to two variables. The first one is for the user data, and the second one is for the profile data.


  {% parse_json payload %}
    "username": "user name",
    "email": "[email protected]",
    "password": {{ "password" | json }},
    "agreed": "true"
  {% endparse_json %}


  {% parse_json profile %}
    "first_name": "first name",
    "last_name": "last name",
    "phone": "1234234"
  {% endparse_json %}

Then you create the user along with this function:

{% liquid
function user = 'lib/commands/users/create', object: payload, profile: profile

Validation check:

{% liquid
unless user.valid
  include 'test/register_error', contract: contract, field_name: 'user#valid', message: user.errors

The test will try to find the user in the database by user ID (in the key field we want to display proper message in logs to inform you what you expected):

{% liquid
function u = 'lib/queries/users/find', id: user.id

unless u
  include 'test/register_error', contract: contract, field_name: 'primary user', key: 'app.test.should.be_valid'

The test will try to create the user with the same credentials. It checks whether user2 is created.

{% liquid
function user2 = 'lib/commands/users/create', object: payload

if user2.valid
  include 'test/register_error', contract: contract, field_name: 'extra user', key: 'app.test.should.not.be_valid'

if user2.id
  include 'test/register_error', contract: contract, field_name: 'extra user', key: 'app.test.should.not.be_valid'

The test deletes the user, and checks if the user exists in the database by user ID.

{% liquid
function deleted = 'lib/commands/users/delete', object: u

function u = 'lib/queries/users/find', id: user.id

if u
  include 'test/register_error', contract: contract, field_name: 'deleted user', key: 'app.test.should.be_valid'

Contribute to this page

Github Icon


We are always happy to help with any questions you may have.

contact us