File Assets and Data-Driven Test Parameterization

Use a File asset when a test needs a file at runtime. A File asset can be an upload payload, such as a PDF or image, or an external test-data source such as a CSV, JSON, or XLSX file.

File assets are shared with the team. Play stages the current file version when the test runs, so tests refer to the asset rather than to a local computer path.

End-to-end workflow

  1. In the asset explorer, create a File asset in the required team or folder.

  2. Open the File asset and select Upload file. Give the asset a meaningful name, for example Customer test data or Invoice PDF.

  3. Open the test case that will use the file.

  4. Drag the File asset from the explorer to the test case References panel. This links the asset to the test and generates a line similar to:

const customerTestData = leapwork.files.path('FL-23');
  1. Use that staged path in the Playwright source. Run the test.

FL-23 is an example display ID. Keep the generated ID in your source; do not replace it with a path from your own machine.

Note: A test can only use files that are linked in its References panel. Linking ensures the correct current version is staged for the run.

Uploading a file to the application under test

For an upload control, pass the staged asset path to Playwright's setInputFiles:

const invoicePdf = leapwork.files.path('FL-23');

await leapwork.step("Upload invoice", async () => {
    await page
        .locator('input[type="file"]')
        .setInputFiles(invoicePdf);
}, {
    action: "upload",
});

You can also drag a File asset while recording an upload action. Play creates the setInputFiles(leapwork.files.path(...)) statement automatically.

Parameterize a test from external data

Store each test scenario as a row (CSV/XLSX) or object (JSON), then read a scenario at runtime and use its values in the test. The examples below use the first scenario; select a different row or object to run another data set.

Use consistent field names across your files, for example name, email, and expectedMessage.

CSV

Example customers.csv:

name,email,expectedMessage
Ada Lovelace,ada@example.com,Customer created
Grace Hopper,grace@example.com,Customer created

The xlsx package available in the test runtime can read CSV files:

const customerDataPath = leapwork.files.path('FL-24');
const XLSX = require("xlsx");

const workbook = XLSX.readFile(customerDataPath);
const sheet = workbook.Sheets[workbook.SheetNames[0]];
const customers = XLSX.utils.sheet_to_json(sheet) as Array<{
    name: string;
    email: string;
    expectedMessage: string;
}>;
const customer = customers[0];

await leapwork.step("Create customer from CSV", async () => {
    await page.getByLabel("Name").fill(customer.name);
    await page.getByLabel("Email").fill(customer.email);
    await page.getByRole("button", { name: "Save" }).click();
    await expect(page.getByText(customer.expectedMessage)).toBeVisible();
});

JSON

Example customers.json:

JSON
[
  { "name": "Ada Lovelace", "email": "ada@example.com", "expectedMessage": "Customer created" },
  { "name": "Grace Hopper", "email": "grace@example.com", "expectedMessage": "Customer created" }
]

Read and parse the staged file with Node's file system module:

const customerDataPath = leapwork.files.path('FL-25');
const { readFileSync } = require("fs");

const customers = JSON.parse(readFileSync(customerDataPath, "utf8")) as Array<{
    name: string;
    email: string;
    expectedMessage: string;
}>;
const customer = customers[0];

await leapwork.step("Create customer from JSON", async () => {
    await page.getByLabel("Name").fill(customer.name);
    await page.getByLabel("Email").fill(customer.email);
});

XLSX (Excel)

Create a worksheet with a header row matching the property names. For example:

name

email

expectedMessage

Ada Lovelace

ada@example.com

Customer created

Grace Hopper

grace@example.com

Customer created

Read it with xlsx:

const customerDataPath = leapwork.files.path('FL-26');
const XLSX = require("xlsx");

const workbook = XLSX.readFile(customerDataPath);
const sheet = workbook.Sheets["Customers"] ?? workbook.Sheets[workbook.SheetNames[0]];
const customers = XLSX.utils.sheet_to_json(sheet) as Array<{
    name: string;
    email: string;
    expectedMessage: string;
}>;
const customer = customers[0];

await leapwork.step("Create customer from Excel", async () => {
    await page.getByLabel("Name").fill(customer.name);
    await page.getByLabel("Email").fill(customer.email);
    await page.getByRole("button", { name: "Save" }).click();
});

Use every row as a separate scenario

Loop through the data to execute the same journey for every row. Give each leapwork.step a data-specific name so the run report is easy to read.

for (const customer of customers) {
    await leapwork.step(`Create customer: ${ customer.email }`, async () => {
        await page.getByLabel("Name").fill(customer.name);
        await page.getByLabel("Email").fill(customer.email);
        await page.getByRole("button", { name: "Save" }).click();
        await expect(page.getByText(customer.expectedMessage)).toBeVisible();
    });
}

Choose this approach when the scenarios can safely run one after another in the same test. If each data set needs its own browser session, create separate test cases or runlists that use the same data source with a different selected record.

Updating data safely

  • Select Upload new version on the File asset to replace its current data without changing the asset reference in tests.

  • The latest uploaded version is used for subsequent runs.

  • Do not rename or delete columns/properties that test code reads until the code is updated as well.

  • Never store passwords, API keys, or other secrets in a File asset. Use Team Secrets instead.

Troubleshooting

Problem

What to check

leapwork.files.path(...) cannot find a file

Drag the File asset into the test case References panel and confirm the asset has an uploaded current version.

Test uses an old file

Upload a new version, then start a new run. A running test keeps the version staged at its start.

XLSX data is empty

Check the worksheet name and ensure the first row contains column headers.

A value is unexpectedly blank

Check that the CSV/XLSX header or JSON property exactly matches the field accessed in code.