Skip to main content

Class: FileInputDriver

Defined in: component-driver-astryx/src/components/FileInputDriver.ts:24

Driver for the Astryx FileInput (@astryxdesign/core/FileInput).

Astryx forwards data-testid onto the hidden native <input type="file">, not the visible div[role="button"] dropzone — which is convenient, because the input is the element every meaningful read and the upload itself live on: accept, multiple, aria-required, aria-invalid, disabled, and the aria-describedby → status-message link are all attributes of the input, and setInputFiles must target a real <input type="file">. The scene therefore anchors this driver on that input.

It extends HTMLFileInputDriver to inherit uploadFiles (the setInputFiles primitive — userEvent.upload in jsdom, locator.setInputFiles in Playwright), and resolves its label through the shared <label for>↔id helper. The rendered selected-file list is consumer-value-controlled, and the OS file picker and drag-and-drop are native — so file-chip readback and dropzone DnD are E2E-only and not surfaced here.

Extends​

  • HTMLFileInputDriver

Constructors​

Constructor​

new FileInputDriver(locator, interactor, option?): FileInputDriver

Defined in: component-driver-html/dist/index.d.mts:119

Create a file input driver.

Parameters​

locator​

PartLocator

interactor​

Interactor

option?​

Partial<IComponentDriverOption<{ }>>

Returns​

FileInputDriver

Inherited from​

HTMLFileInputDriver.constructor

Properties​

commutableOption​

readonly commutableOption: IComponentDriverOption<{ }>

Defined in: core/dist/index.d.mts:999

Option passed to the constructor includes both universal options which can be shared across all component driver tree, and component specific options which are only applicable to the component.

Commutable option is the option that can be shared across all component driver tree.

Inherited from​

HTMLFileInputDriver.commutableOption

interactor​

readonly interactor: Interactor

Defined in: core/dist/index.d.mts:990

Inherited from​

HTMLFileInputDriver.interactor

Accessors​

driverName​

Get Signature​

get driverName(): string

Defined in: component-driver-astryx/src/components/FileInputDriver.ts:86

Identifier for this driver.

Returns​

string

Overrides​

HTMLFileInputDriver.driverName

locator​

Get Signature​

get locator(): PartLocator

Defined in: core/dist/index.d.mts:1044

Return the locator of the component

Returns​

PartLocator

Inherited from​

HTMLFileInputDriver.locator

parts​

Get Signature​

get parts(): ScenePartDriver<T>

Defined in: core/dist/index.d.mts:1040

Return driver instance of all the named parts

Returns​

ScenePartDriver<T>

Inherited from​

HTMLFileInputDriver.parts

Methods​

activate()​

activate(): Promise<void>

Defined in: core/dist/index.d.mts:1091

Activate the component without relying on pointer geometry. See Interactor.activate.

Returns​

Promise<void>

Inherited from​

HTMLFileInputDriver.activate

click()​

click(option?): Promise<void>

Defined in: core/dist/index.d.mts:1068

Parameters​

option?​

Partial<ClickOption>

Returns​

Promise<void>

Inherited from​

HTMLFileInputDriver.click

contextMenu()​

contextMenu(): Promise<void>

Defined in: core/dist/index.d.mts:1087

Dispatch a right-click / contextmenu event on the component. See Interactor.contextMenu.

Returns​

Promise<void>

Inherited from​

HTMLFileInputDriver.contextMenu

drag()​

drag(delta): Promise<void>

Defined in: core/dist/index.d.mts:1129

Drag this component by the given pixel delta from its center. See Interactor.drag.

Prefer a keyboard-driven setValue over a true drag in real drivers — these drag primitives exist only for cases keyboard cannot express (e.g. panning a Lightbox, reordering a column). jsdom has no layout engine, so the positional outcome of the drag is E2E-only there.

Parameters​

delta​

Point

Pixel offset to drag by

Returns​

Promise<void>

Inherited from​

HTMLFileInputDriver.drag

dragTo()​

dragTo(target): Promise<void>

Defined in: core/dist/index.d.mts:1118

Drag this component and drop it onto another component. See Interactor.dragTo.

Prefer a keyboard-driven setValue over a true drag in real drivers — these drag primitives exist only for cases keyboard cannot express (e.g. panning a Lightbox, reordering a column). jsdom has no layout engine, so the positional outcome of the drag is E2E-only there.

Parameters​

target​

ComponentDriver<any>

Another driver whose root element is the drop target

Returns​

Promise<void>

Inherited from​

HTMLFileInputDriver.dragTo

enforcePartExistence()​

protected enforcePartExistence(partName): Promise<void>

Defined in: core/dist/index.d.mts:1050

Check the specified parts' existences, and throw MissingPartError if any of the part is found not existence. Existence is defined by the part's existence in the DOM regardless of its visibility on the screen

Parameters​

partName​

readonly never[]

Single or array of the names of the parts to be enforced

Returns​

Promise<void>

Inherited from​

HTMLFileInputDriver.enforcePartExistence

exists()​

exists(): Promise<boolean>

Defined in: core/dist/index.d.mts:1067

Whether the component exists/attached to the DOM

Returns​

Promise<boolean>

true if the component is attached to the DOM, false otherwise

Inherited from​

HTMLFileInputDriver.exists

focus()​

focus(option?): Promise<void>

Defined in: core/dist/index.d.mts:1077

Parameters​

option?​

Partial<FocusOption>

Returns​

Promise<void>

Inherited from​

HTMLFileInputDriver.focus

getAccept()​

getAccept(): Promise<Optional<string>>

Defined in: component-driver-astryx/src/components/FileInputDriver.ts:26

The accepted MIME/extension filter (accept), or undefined when unrestricted.

Returns​

Promise<Optional<string>>

getAttribute()​

getAttribute(attributeName): Promise<Optional<string>>

Defined in: core/dist/index.d.mts:1062

Parameters​

attributeName​

string

Returns​

Promise<Optional<string>>

Inherited from​

HTMLFileInputDriver.getAttribute

getBoundingRect()​

getBoundingRect(): Promise<BoundingRect>

Defined in: core/dist/index.d.mts:1136

Get this component's bounding rectangle. See Interactor.getBoundingRect.

jsdom has no layout engine, so every coordinate and dimension is 0 there; real geometry is E2E-only.

Returns​

Promise<BoundingRect>

Inherited from​

HTMLFileInputDriver.getBoundingRect

getLabel()​

getLabel(): Promise<Optional<string>>

Defined in: component-driver-astryx/src/components/FileInputDriver.ts:56

The field's visible label, resolved through the native <label for>↔id link rather than a StyleX-hashed wrapper class. The id is matched through the escaping byLinkedElement builder (shared with the field-input drivers), so a consumer-supplied id with a CSS metacharacter cannot break the selector.

Returns​

Promise<Optional<string>>

getMissingPartNames()​

protected getMissingPartNames(partName): Promise<readonly never[]>

Defined in: core/dist/index.d.mts:1056

Get the names of parts not in the DOM

Parameters​

partName​

readonly never[]

Single or array of the names of the parts to be examined

Returns​

Promise<readonly never[]>

Inherited from​

HTMLFileInputDriver.getMissingPartNames

getStatusMessage()​

getStatusMessage(): Promise<Optional<string>>

Defined in: component-driver-astryx/src/components/FileInputDriver.ts:72

The validation message text, resolved through the input's aria-describedby → status element id link. undefined when the field carries no status.

aria-describedby is an IDREF list: Astryx points the input at both its description and its status when both are present (FileInput joins descriptionID + statusMessageID). The status is the FieldStatus element carrying a data-type severity marker (the description is a plain element without it), so each id is resolved and the one with data-type is returned — matching the whole multi-id attribute as a single id would find nothing. This mirrors AstryxFieldInputDriver.getStatusMessage.

Returns​

Promise<Optional<string>>

getText()​

getText(): Promise<Optional<string>>

Defined in: core/dist/index.d.mts:1061

Get the combined text content of the component

Returns​

Promise<Optional<string>>

If the component exists and has content, it should return the text or otherwise undefined

Inherited from​

HTMLFileInputDriver.getText

hover()​

hover(option?): Promise<void>

Defined in: core/dist/index.d.mts:1069

Parameters​

option?​

Partial<HoverOption>

Returns​

Promise<void>

Inherited from​

HTMLFileInputDriver.hover

innerHTML()​

innerHTML(): Promise<string>

Defined in: core/dist/index.d.mts:1168

Get the inner HTML of the component

Returns​

Promise<string>

The inner HTML of the component

Inherited from​

HTMLFileInputDriver.innerHTML

isDisabled()​

isDisabled(): Promise<boolean>

Defined in: component-driver-astryx/src/components/FileInputDriver.ts:46

Whether the field is disabled (native disabled on the input).

Returns​

Promise<boolean>

isInvalid()​

isInvalid(): Promise<boolean>

Defined in: component-driver-astryx/src/components/FileInputDriver.ts:41

Whether the field is in an error state (aria-invalid="true", mirrored by the button's data-status="error").

Returns​

Promise<boolean>

isMultiple()​

isMultiple(): Promise<boolean>

Defined in: component-driver-astryx/src/components/FileInputDriver.ts:31

Whether multiple files may be selected (multiple).

Returns​

Promise<boolean>

isRequired()​

isRequired(): Promise<boolean>

Defined in: component-driver-astryx/src/components/FileInputDriver.ts:36

Whether the field is required (aria-required="true").

Returns​

Promise<boolean>

isVisible()​

isVisible(): Promise<boolean>

Defined in: core/dist/index.d.mts:1145

Whether the component is visible. Visibility is defined that the component does not have the CSS property display: none, visibility: hidden, or opacity: 0. However this does not check whether the component is within the viewport.

Returns​

Promise<boolean>

true if the component is visible, false otherwise

Inherited from​

HTMLFileInputDriver.isVisible

mouseDown()​

mouseDown(option?): Promise<void>

Defined in: core/dist/index.d.mts:1071

Parameters​

option?​

Partial<MouseDownOption>

Returns​

Promise<void>

Inherited from​

HTMLFileInputDriver.mouseDown

mouseEnter()​

mouseEnter(option?): Promise<void>

Defined in: core/dist/index.d.mts:1075

Parameters​

option?​

Partial<MouseEnterOption>

Returns​

Promise<void>

Inherited from​

HTMLFileInputDriver.mouseEnter

mouseLeave()​

mouseLeave(option?): Promise<void>

Defined in: core/dist/index.d.mts:1076

Parameters​

option?​

Partial<MouseLeaveOption>

Returns​

Promise<void>

Inherited from​

HTMLFileInputDriver.mouseLeave

mouseMove()​

mouseMove(option?): Promise<void>

Defined in: core/dist/index.d.mts:1070

Parameters​

option?​

Partial<MouseMoveOption>

Returns​

Promise<void>

Inherited from​

HTMLFileInputDriver.mouseMove

mouseOut()​

mouseOut(option?): Promise<void>

Defined in: core/dist/index.d.mts:1074

Parameters​

option?​

Partial<MouseOutOption>

Returns​

Promise<void>

Inherited from​

HTMLFileInputDriver.mouseOut

mouseOver()​

mouseOver(option?): Promise<void>

Defined in: core/dist/index.d.mts:1073

Parameters​

option?​

Partial<HoverOption>

Returns​

Promise<void>

Inherited from​

HTMLFileInputDriver.mouseOver

mouseUp()​

mouseUp(option?): Promise<void>

Defined in: core/dist/index.d.mts:1072

Parameters​

option?​

Partial<MouseUpOption>

Returns​

Promise<void>

Inherited from​

HTMLFileInputDriver.mouseUp

pressKey()​

pressKey(key, option?): Promise<void>

Defined in: core/dist/index.d.mts:1083

Dispatch a keyboard key press on the component. See Interactor.pressKey.

Parameters​

key​

string

A KeyboardEvent.key value, e.g. 'Escape', 'Backspace', 'Enter'

option?​

Partial<PressKeyOption>

Reserved for future modifier-key support

Returns​

Promise<void>

Inherited from​

HTMLFileInputDriver.pressKey

runtimeCssSelector()​

runtimeCssSelector(): Promise<string>

Defined in: core/dist/index.d.mts:1174

Get the runtime CSS selector of the component. This is useful for debugging and testing purposes.

Returns​

Promise<string>

The runtime CSS selector of the component

Inherited from​

HTMLFileInputDriver.runtimeCssSelector

scrollBy()​

scrollBy(delta): Promise<void>

Defined in: core/dist/index.d.mts:1107

Scroll the component by the given pixel delta. See Interactor.scrollBy.

jsdom has no layout engine, so the scroll is a no-op there and behavioral assertions (resulting offset) are E2E-only.

Parameters​

delta​

Point

Pixel offset to scroll by

Returns​

Promise<void>

Inherited from​

HTMLFileInputDriver.scrollBy

scrollIntoView()​

scrollIntoView(): Promise<void>

Defined in: core/dist/index.d.mts:1098

Scroll the component into the viewport. See Interactor.scrollIntoView.

jsdom has no layout engine, so the scroll is a no-op there and behavioral assertions (visibility, offset) are E2E-only.

Returns​

Promise<void>

Inherited from​

HTMLFileInputDriver.scrollIntoView

uploadFiles()​

uploadFiles(files): Promise<void>

Defined in: component-driver-html/dist/index.d.mts:130

Select one or more files on the <input type="file"> element.

A file input cannot be filled via HTMLTextInputDriver.setValue — browsers block programmatic value assignment on type=file — so this delegates to the dedicated setInputFiles interactor primitive.

Parameters​

files​

string | string[]

One or more filesystem paths. Pass a single path for a non-multiple input; pass an array for a multiple input.

Returns​

Promise<void>

Inherited from​

HTMLFileInputDriver.uploadFiles

waitUntil()​

waitUntil<T>(option): Promise<T>

Defined in: core/dist/index.d.mts:1163

Type Parameters​

T​

T

Parameters​

option​

WaitUntilOption<T>

Returns​

Promise<T>

Inherited from​

HTMLFileInputDriver.waitUntil

waitUntilComponentState()​

waitUntilComponentState(option?): Promise<void>

Defined in: core/dist/index.d.mts:1162

Wait until the component is in the expected state such as the component's visibility or existence. If the component has not reached the expected state within the timeout, it will throw an error.

By default it waits until the component is attached to the DOM within 30 seconds.

Parameters​

option?​

Partial<Readonly<WaitForOption>>

The option to configure the wait behavior

Returns​

Promise<void>

Inherited from​

HTMLFileInputDriver.waitUntilComponentState

waitUntilVisible()​

waitUntilVisible(timeoutMs?): Promise<void>

Defined in: core/dist/index.d.mts:1150

Wait until the component is attached and becomes visible to the DOM.

Parameters​

timeoutMs?​

number

The number of milliseconds to wait before timing out

Returns​

Promise<void>

Inherited from​

HTMLFileInputDriver.waitUntilVisible

overriddenParentLocator()​

static overriddenParentLocator(): Optional<PartLocator>

Defined in: core/dist/index.d.mts:1026

Portal hook: where to re-root this driver's locator when its component renders outside the parent's DOM (a modal, popup, drawer). Return the PartLocator that locates the component from the document root, or undefined (the default) for normal in-tree components whose locator chains from the parent.

This is static because it is per-class metadata read off the constructor before any instance exists — which makes the "no instance state" constraint structural rather than a documented caution. Override with static override.

Returns​

Optional<PartLocator>

Inherited from​

HTMLFileInputDriver.overriddenParentLocator

overrideLocatorRelativePosition()​

static overrideLocatorRelativePosition(): Optional<LocatorRelativePosition>

Defined in: core/dist/index.d.mts:1036

Portal hook: the locator relative position to apply when the component's real DOM is a sibling/elsewhere rather than a descendant (e.g. a MUI dialog rendered at the document root, located by a "Same"-level selector). Return undefined (the default) to keep the natural position declared by the ScenePart.

Static for the same reason as ComponentDriver.overriddenParentLocator: it is class-level metadata read before construction. Override with static override.

Returns​

Optional<LocatorRelativePosition>

Inherited from​

HTMLFileInputDriver.overrideLocatorRelativePosition