Downloading a file, a popup window, a server response - all of these are events that happen in reply to an action, and here it is easy to create a race. Naive code presses a button and then tries to get the event - but between the press and the attempt the event could already have happened and passed unnoticed. The right order is the opposite of intuition: first start waiting for the event, then perform the action, and only then await the result. This shift removes a whole class of instability.

Downloading is the canonical example. First you create a wait promise via page.waitForEvent('download') without awaiting it, then press the button that starts the download, and only after that await the promise. So there is no gap between the action and the wait through which the event could slip. The resulting download object carries metadata - the suggested filename - and can save the content wherever the test says.

Checking a downloaded file is convenient through its properties and content. suggestedFilename() returns the name the server suggested to the browser - you compare it with the expected. saveAs saves the file, into the path given by testInfo.outputPath - the artifact directory of this specific test, isolated from others. So the downloaded file is both checked and stays attached to the test result for later analysis, without interfering with parallel scenarios.

Uploading a file is simpler and does not require a real file on disk. setInputFiles takes a file description right in the code - a name, a mime type and content as a buffer - and passes it to the upload field. This is convenient and deterministic: the test does not depend on a file being in the repository and its path but forms the needed file on the spot. For an avatar, a document, an image it is enough to assemble a buffer and hand it to the field by its label.

It helps to see both patterns side by side once - downloading with the wait before the action and uploading via a buffer. Below is a download without a race and an avatar upload. You return to this pair when a file interaction appears in a scenario: first you decide who initiates the event and when to start waiting for it, and only then write the action itself.

The same "wait before the action" principle extends to other events. A popup window (a new tab) is caught by waiting for the 'page' event on the context before the click that opens it. A specific network response - via waitForResponse with a predicate before the action that triggers the request. A file chooser dialog, a payment popup, a new OAuth window - all share one shape: a wait promise, then the action, then await. Different event nature, the same code structure.