Files

Check the files your services and apps write to a folder: an export directory, a volume they share with Axx, an app’s own data.

Register the folder with the {word} folder with the following properties:. Its path is on this machine, relative to the directory of axx.yaml or absolute, or in the file context of its owner: service:parcels for a service of axx.yaml (relative to the folder Axx runs it in), app:depot for an app a scenario registers (./ is where the app keeps its data, ~/ its home, wherever it runs). ${env:..} and ${sys:..} are expanded. A check names a file by its path in the folder, such as manifests/M-KESTREL-0412/report.csv, quoted when it has a space, and waits for it (10 seconds unless within {duration} says otherwise), since services write asynchronously.

The checks are those of the storage packs’ objects: a file’s exact content, its JSON properties, its text, read by its type (PDF, Word, Excel, CSV, JSON, XML, HTML or plain text), and a row of its table (CSV, TSV or Excel). What a service or an app takes away is checked too: a folder has no file named one, or is empty, which wait for the files to go. An image an app saves is compared with its screenshot, pixel by pixel, one for each platform: packs.files.screenshots sets their folder, tolerance, update and platforms, as the app screenshots’ settings do.

A scenario puts files in a folder too, as a service or an app would find them: is a copy of a file of the project, or has the content: of a doc string. the {word} folder is emptied removes what is in it, hidden files and subfolders too: a folder of the project, a service’s or an app’s, never one elsewhere on the machine.

A service’s folder keeps what earlier runs wrote there, and Axx empties no folder unless a scenario says so: whether a check needs a file of its scenario’s own (named after data unique to it), or a folder emptied first, depends on the test. An app’s files are its own in each scenario.

Add it to a project with axx pack add files.

Settings

In axx.yaml, under packs.files:

Setting	Takes	Values	Default
screenshots.folder	The folder of the images’ screenshots, in the project. Unset, each feature keeps its screenshots in a screenshots folder next to its file.	text
screenshots.platforms	The platforms whose screenshots the project keeps: each compares its own; elsewhere the step passes without comparing (default: every platform).	a list of linux, darwin, windows
screenshots.tolerance	The share of an image’s pixels that may differ.	a number, 0 to 1	0
screenshots.update	Take every screenshot again, as the image is now, instead of comparing.	true, false

Steps

files.folder

Given the {word} folder with the following properties:
  | property | value |

The table may start with the row naming its columns, as above, or go straight to its rows.

Register a folder under a name. The folder may appear only when a service first writes to it.

Parameter	Takes	For example
{word}	one word, with no spaces	parcels, PX-4101

Property	Takes	Default
path	the folder: with no owner, a path relative to the directory of axx.yaml, or absolute; with one, a path in its file context (./exports); ${env:..} and ${sys:..} are expanded	required
owner	whose folder it is: service:<name>, a service of axx.yaml, whose paths are relative to the folder Axx runs it in; or app:<name>, an app the scenario registers, where ./ is where the app keeps its data and ~/ its home	none: a folder on this machine

Example:

Given the exports folder with the following properties:
  | owner | service:parcels |
  | path  | ./exports       |
Given the desk folder with the following properties:
  | owner | app:depot              |
  | path  | "./Parcels/Depot desk" |

Since 0.1.1.

files.copy

Given the {path} file in the {word} folder is a copy of the {filepath} file

Put a copy of a file of the project in the folder, under the path given, as a service or an app would find it there; the folders it is in are made, and a file there is replaced.

Parameter	Takes	For example
{path}	a path in a folder or a store, like manifests/M-1/report.csv, quoted when it has a space. A * stands for any characters but a slash, for a name a check cannot know (snap-*.json, named by the time): the path then names the one file it matches	manifests/M-KESTREL-0412/report.csv, "Parcels/Depot desk/arrivals.json"
{word}	one word, with no spaces	parcels, PX-4101
{filepath}	a file of the project: a path relative to the feature file’s directory, the resources directories or axx.yaml’s directory (looked for in that order), or an absolute path, quoted when it has a space	seeds/parcels.yaml, kafka/scan-delivered.json

Example:

Given the manifests/M-KESTREL-0505/report.csv file in the exports folder is a copy of the reports/M-KESTREL-0505-earlier.csv file

Since 0.2.3.

files.content

Given the {path} file in the {word} folder has the content:
  """
  ...
  """

Put a file with the doc string’s content in the folder, as a service or an app would find it there; the folders it is in are made, and a file there is replaced. ${env:..} and ${sys:..} are expanded.

Parameter	Takes	For example
{path}	a path in a folder or a store, like manifests/M-1/report.csv, quoted when it has a space. A * stands for any characters but a slash, for a name a check cannot know (snap-*.json, named by the time): the path then names the one file it matches	manifests/M-KESTREL-0412/report.csv, "Parcels/Depot desk/arrivals.json"
{word}	one word, with no spaces	parcels, PX-4101

Example:

Given the manifests/M-KESTREL-0505/summary.json file in the exports folder has the content:
  """json
  {"manifest": "M-KESTREL-0505", "lines": 1}
  """

Since 0.2.3.

files.emptied

Given the {word} folder is emptied

Remove everything in the folder, hidden files and subfolders too, and keep the folder: a folder of the project, a service’s or an app’s. A folder elsewhere on this machine is a person’s, and is not emptied.

Parameter	Takes	For example
{word}	one word, with no spaces	parcels, PX-4101

Example:

Given the kestrel folder is emptied

Since 0.2.3.

files.has

Then [[within {duration} ]]the {word} folder has a(n) file named {path}

Check that the folder has a file with that name. The check waits for it: 10 seconds, or within {duration}.

Parameter	Takes	For example
{duration}	a duration in seconds (s) or minutes (m)	5s, 2m
{word}	one word, with no spaces	parcels, PX-4101
{path}	a path in a folder or a store, like manifests/M-1/report.csv, quoted when it has a space. A * stands for any characters but a slash, for a name a check cannot know (snap-*.json, named by the time): the path then names the one file it matches	manifests/M-KESTREL-0412/report.csv, "Parcels/Depot desk/arrivals.json"

Variants, the parts in [[...]] said or left out:

• the {word} folder has a(n) file named {path}
• within {duration} the {word} folder has a(n) file named {path}

Example:

Then within 30s the exports folder has a file named disputes/kestrel-2026-09.csv

Since 0.1.1.

files.identical

Then [[within {duration} ]]the {path} file in the {word} folder is identical to the {filepath} file

Check that the file exists with exactly the content of the file. The check waits for it: 10 seconds, or within {duration}.

Parameter	Takes	For example
{duration}	a duration in seconds (s) or minutes (m)	5s, 2m
{path}	a path in a folder or a store, like manifests/M-1/report.csv, quoted when it has a space. A * stands for any characters but a slash, for a name a check cannot know (snap-*.json, named by the time): the path then names the one file it matches	manifests/M-KESTREL-0412/report.csv, "Parcels/Depot desk/arrivals.json"
{word}	one word, with no spaces	parcels, PX-4101
{filepath}	a file of the project: a path relative to the feature file’s directory, the resources directories or axx.yaml’s directory (looked for in that order), or an absolute path, quoted when it has a space	seeds/parcels.yaml, kafka/scan-delivered.json

Variants, the parts in [[...]] said or left out:

• the {path} file in the {word} folder is identical to the {filepath} file
• within {duration} the {path} file in the {word} folder is identical to the {filepath} file

Example:

Then the disputes/kestrel-2026-09.csv file in the exports folder is identical to the expected/kestrel-disputes.csv file

Since 0.1.1.

files.properties

Then [[within {duration} ]]the {path} file in the {word} folder has the following properties:
  | path | value |

The table may start with the row naming its columns, as above, or go straight to its rows.

Check that the file holds JSON with those values at those paths. The check waits for it: 10 seconds, or within {duration}.

Parameter	Takes	For example
{duration}	a duration in seconds (s) or minutes (m)	5s, 2m
{path}	a path in a folder or a store, like manifests/M-1/report.csv, quoted when it has a space. A * stands for any characters but a slash, for a name a check cannot know (snap-*.json, named by the time): the path then names the one file it matches	manifests/M-KESTREL-0412/report.csv, "Parcels/Depot desk/arrivals.json"
{word}	one word, with no spaces	parcels, PX-4101

Each row is a path into the JSON (a property name, a dotted path or a JSONPath) and the value it has, compared as text: null for null and undefined for absent, as in the other JSON property steps.

Variants, the parts in [[...]] said or left out:

• the {path} file in the {word} folder has the following properties:
• within {duration} the {path} file in the {word} folder has the following properties:

Example:

Then the summaries/kestrel-2026-09.json file in the exports folder has the following properties:
  | carrier         | KESTREL |
  | lines           | 14      |
  | totals.disputed | 5.25    |

Since 0.1.1.

files.contains

Then [[within {duration} ]]the {path} file in the {word} folder contains {string}

Check that the text of the file contains the text.

• The check waits for it: 10 seconds, or within {duration}.
• Case matters; runs of spaces and line breaks count as one space.
• The text is read by the file’s type: the text of a PDF’s pages, the paragraphs and tables of a Word document (.docx), the cells of every sheet of an Excel workbook (.xlsx), the text content (or the markup) of XML and HTML, or the text itself.

Parameter	Takes	For example
{duration}	a duration in seconds (s) or minutes (m)	5s, 2m
{path}	a path in a folder or a store, like manifests/M-1/report.csv, quoted when it has a space. A * stands for any characters but a slash, for a name a check cannot know (snap-*.json, named by the time): the path then names the one file it matches	manifests/M-KESTREL-0412/report.csv, "Parcels/Depot desk/arrivals.json"
{word}	one word, with no spaces	parcels, PX-4101
{string}	text in double or single quotes, which the step leaves out	"Get a quote", 'Express'

Variants, the parts in [[...]] said or left out:

• the {path} file in the {word} folder contains {string}
• within {duration} the {path} file in the {word} folder contains {string}

Example:

Then the invoices/kestrel-2026-09.pdf file in the exports folder contains "Total due: 1284.50 EUR"

Since 0.1.1.

files.row

Then [[within {duration} ]]the {path} file in the {word} folder has a row where:
  | column | value |

The table may start with the row naming its columns, as above, or go straight to its rows.

Check that the table of the file has a row with those values in those columns.

• The check waits for it: 10 seconds, or within {duration}.
• The file is a CSV or TSV file, or an Excel workbook (.xlsx; its first sheet), whose first row names the columns.
• Cells compare as text, as the workbook shows them, with runs of spaces as one space; an empty value matches an empty cell.

Parameter	Takes	For example
{duration}	a duration in seconds (s) or minutes (m)	5s, 2m
{path}	a path in a folder or a store, like manifests/M-1/report.csv, quoted when it has a space. A * stands for any characters but a slash, for a name a check cannot know (snap-*.json, named by the time): the path then names the one file it matches	manifests/M-KESTREL-0412/report.csv, "Parcels/Depot desk/arrivals.json"
{word}	one word, with no spaces	parcels, PX-4101

Each row names a column, as the file’s first row names it, and the value in that column.

Variants, the parts in [[...]] said or left out:

• the {path} file in the {word} folder has a row where:
• within {duration} the {path} file in the {word} folder has a row where:

Example:

Then within 30s the disputes/kestrel-2026-09.csv file in the exports folder has a row where:
  | parcel | PX-5199          |
  | status | UNKNOWN_SHIPMENT |
  | billed | 4.10             |

Since 0.1.1.

files.absent

Then [[within {duration} ]]the {word} folder has no file named {path}

Check that the folder has no file with that name, or wait for it to go: 10 seconds, or within {duration}, for a service or an app that deletes or moves it.

Parameter	Takes	For example
{duration}	a duration in seconds (s) or minutes (m)	5s, 2m
{word}	one word, with no spaces	parcels, PX-4101
{path}	a path in a folder or a store, like manifests/M-1/report.csv, quoted when it has a space. A * stands for any characters but a slash, for a name a check cannot know (snap-*.json, named by the time): the path then names the one file it matches	manifests/M-KESTREL-0412/report.csv, "Parcels/Depot desk/arrivals.json"

Variants, the parts in [[...]] said or left out:

• the {word} folder has no file named {path}
• within {duration} the {word} folder has no file named {path}

Example:

Then the exports folder has no file named manifests/M-KESTREL-0505/report.csv

Since 0.2.3.

files.empty

Then [[within {duration} ]]the {word} folder is empty

Check that the folder has no files, in its subfolders too, or wait for them to go: 10 seconds, or within {duration}. Hidden files (.DS_Store, .gitkeep) are not counted, and a folder that is not there is empty.

Parameter	Takes	For example
{duration}	a duration in seconds (s) or minutes (m)	5s, 2m
{word}	one word, with no spaces	parcels, PX-4101

Variants, the parts in [[...]] said or left out:

• the {word} folder is empty
• within {duration} the {word} folder is empty

Example:

Then the exports folder is empty

Since 0.2.3.

files.screenshot

Then [[within {duration} ]]the {path} file in the {word} folder looks like the {string} screenshot

Check that an image file looks like its screenshot, pixel by pixel (anti-aliasing aside): an image an app saved, like an annotated capture (PNG or JPEG). The check waits for the file: 10 seconds, or within {duration}.

• Each platform draws images its own way, so each has its own screenshot, named after it (checkout-annotated.darwin.png), in a screenshots folder next to the feature file (or the folder packs.files.screenshots sets).
• Without one, the step takes it and fails: look at it, and keep it.
• When the image is different, the step attaches the screenshot, the image and their difference.

Parameter	Takes	For example
{duration}	a duration in seconds (s) or minutes (m)	5s, 2m
{path}	a path in a folder or a store, like manifests/M-1/report.csv, quoted when it has a space. A * stands for any characters but a slash, for a name a check cannot know (snap-*.json, named by the time): the path then names the one file it matches	manifests/M-KESTREL-0412/report.csv, "Parcels/Depot desk/arrivals.json"
{word}	one word, with no spaces	parcels, PX-4101
{string}	text in double or single quotes, which the step leaves out	"Get a quote", 'Express'

Variants, the parts in [[...]] said or left out:

• the {path} file in the {word} folder looks like the {string} screenshot
• within {duration} the {path} file in the {word} folder looks like the {string} screenshot

Example:

Then the "snap-*.png" file in the inbox folder looks like the "checkout-annotated" screenshot

Since 0.2.1.