Package com.vaadin.flow.component.upload

Class UploadTester<T extends Upload>

java.lang.Object

com.vaadin.browserless.ComponentTester<T>

com.vaadin.flow.component.upload.UploadTester<T>

Type Parameters:

T - the component type.

All Implemented Interfaces:

Clickable<T>

public class UploadTester<T extends Upload>
extends ComponentTester<T>

Tester for Upload components.

Files handed to upload(File) and friends go through the same client-side gate the vaadin-upload web component applies before it sends anything to the server: maxFiles, maxFileSize and the accepted file types are checked in that order, and a file failing any of them is not delivered to the upload handler or receiver. Instead a FileRejectedEvent is fired, exactly as it would be in a browser.

A refused file is no more of an error in the tester than it is in the browser, so uploading does not throw for it. Use getLastUploadStatus() to see what became of each file, or ensureUploaded() to fail the test unless every file went through.

maxFiles is checked against an emulated file list, so files stay in it between calls just like the entries the browser shows: uploading two files to an Upload configured with a plain Receiver rejects the second one, because such an Upload implicitly sets maxFiles to one. Use removeFile(String) or Upload.clearFileList() to make room, as the user would.

Accepted files are uploaded right away unless auto upload is turned off, in which case they wait in the file list, UploadTester.UploadStatus.PENDING, until the test starts them with startUpload(String), as the user would with the start button of the entry.

As in the browser, the same file, or another file with the same name, can be uploaded more than once: every upload adds an entry of its own to the file list, is delivered on its own and counts towards maxFiles. When several entries share a name, removeFile(String) removes the most recently added one, which is the first one the list shows, and startUpload(String) starts the most recently added one that still waits to be started. To act on a specific entry, use removeFile(int) and startUpload(int) with its position in getFiles().

The accepted file types are checked the way the web component does, against the file name or the content type. That is a laxer rule than the server side validation Flow applies to Upload.setAcceptedMimeTypes(String...) and Upload.setAcceptedFileExtensions(String...), which the file has to pass as well before it reaches the upload handler.

Since:

1.0

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final record	UploadTester.FileStatus	Outcome of a single file of an upload simulated by the tester.
static enum	UploadTester.UploadStatus	What became of a file handed to the tester for uploading.

Constructor Summary

Constructors

Constructor	Description
UploadTester(T component)	Wrap given component for testing.

Method Summary

Modifier and Type	Method	Description
void	ensureUploaded()	Checks that the upload last simulated on this component delivered every one of its files, and fails otherwise.
void	ensureUploadFailed()	Checks that at least one file of the upload last simulated on this component failed or was rejected, and fails otherwise.
List<UploadTester.FileStatus>	getFiles()	Gets the files the upload file list shows, in the order the browser shows them: the most recently added file first.
List<UploadTester.FileStatus>	getLastUploadStatus()	Returns what happened to each file of the upload last simulated on this component, in the order the files were given, so that a test can check the outcome the same way a user reads the upload file list in the browser.
void	removeFile(int index)	Simulates the user removing the file at the given position of the upload file list, as if clicking the remove button on that entry.
void	removeFile(File file)	Simulates the user removing a file from the upload file list, as if clicking the remove button on the file entry.
void	removeFile(String fileName)	Simulates the user removing a file from the upload file list, as if clicking the remove button on the file entry.
void	startUpload(int index)	Simulates the user clicking the start button of the file at the given position of the upload file list, which waits because auto upload is turned off, uploading it.
void	startUpload(File file)	Simulates the user clicking the start button of a file that waits in the upload file list because auto upload is turned off, uploading it.
void	startUpload(String fileName)	Simulates the user clicking the start button of a file that waits in the upload file list because auto upload is turned off, uploading it.
void	upload(File file)	Send the file data to the Upload component as if it is uploaded in the browser.
void	upload(String fileName, String contentType, byte[] contents)	Send the file data to the Upload component as if it is uploaded in the browser.
void	upload(String fileName, String contentType, InputStream contents)	Send the file data to the Upload component as if it is uploaded in the browser.
void	uploadAborted(File file)	Simulates upload interruption by user on browser.
void	uploadAborted(String fileName, String contentType)	Simulates upload interruption by user on browser.
void	uploadAll(File... files)	Simulates uploading multiple files at once.
void	uploadAll(Collection<File> files)	Simulates uploading multiple files at once.
void	uploadFailed(File file)	Simulates a failure during file upload.
void	uploadFailed(String fileName, String contentType)	Simulates a failure during file upload.

Methods inherited from class com.vaadin.browserless.ComponentTester

blur, canSetValueAsUser, clearAsUser, clickClearButtonAsUser, ensureComponentIsUsable, ensureComponentIsUsable, ensureComponentIsUsableOrDetach, ensureVisible, ensureVisible, find, findAllByQuery, findByQuery, fireDomEvent, fireDomEvent, fireDomEvent, focus, getComponent, getField, getField, getMethod, getMethod, isComponentReadOnly, isFocused, isUsable, isUsable, notUsableReasons, notUsableReasons, roundTrip, setModal, setPropertyAsUser, setValueAsUser, setValueAsUser

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.vaadin.browserless.Clickable

click, click, click, middleClick, middleClick, rightClick, rightClick

Constructor Details

UploadTester

public UploadTester(T component)

Wrap given component for testing.

Parameters:

component - target component

Method Details

upload

public void upload(String fileName,
 String contentType,
 InputStream contents)

Send the file data to the Upload component as if it is uploaded in the browser.

The file is rejected with a FileRejectedEvent, and never reaches the upload handler, if it violates one of the client-side constraints of the component. With auto upload turned off, an accepted file waits in the file list until startUpload(String) is called.

Parameters:

fileName - name of the file to upload

contentType - content type of the file to upload

contents - file contents as an array of bytes

Throws:

UncheckedIOException - if the upload component fails to handle file contents

IllegalStateException - if the component is not usable

upload

public void upload(String fileName,
 String contentType,
 byte[] contents)

Send the file data to the Upload component as if it is uploaded in the browser.

The file is rejected with a FileRejectedEvent, and never reaches the upload handler, if it violates one of the client-side constraints of the component. With auto upload turned off, an accepted file waits in the file list until startUpload(String) is called.

Parameters:

fileName - name of the file to upload

contentType - content type of the file to upload

contents - file contents as an array of bytes

Throws:

UncheckedIOException - if the upload component fails to handle file contents

IllegalStateException - if the component is not usable

upload

public void upload(File file)

Send the file data to the Upload component as if it is uploaded in the browser. The content type is detected from file name.

The file is rejected with a FileRejectedEvent, and never reaches the upload handler, if it violates one of the client-side constraints of the component. With auto upload turned off, an accepted file waits in the file list until startUpload(String) is called.

Parameters:

file - the file to upload

Throws:

UncheckedIOException - if the upload component fails to handle file contents

IllegalStateException - if the component is not usable

uploadAll

public void uploadAll(File... files)

Simulates uploading multiple files at once.

Files violating one of the client-side constraints of the component are rejected with a FileRejectedEvent and never reach the upload handler; the remaining files are uploaded, or wait in the file list when auto upload is turned off.

Parameters:

files - files to upload

Throws:

IllegalStateException - if the component is not usable

uploadAll

public void uploadAll(Collection<File> files)

Simulates uploading multiple files at once.

Files violating one of the client-side constraints of the component are rejected with a FileRejectedEvent and never reach the upload handler; the remaining files are uploaded, or wait in the file list when auto upload is turned off.

Parameters:

files - files to upload

Throws:

IllegalStateException - if the component is not usable

uploadAborted

public void uploadAborted(String fileName,
 String contentType)

Simulates upload interruption by user on browser.

As in the browser, the interrupted file is dropped from the file list and a FileRemovedEvent is fired, freeing a slot when Upload.setMaxFiles(int) is in use.

The file is added and its transfer started in one go, whether or not auto upload is turned off.

Parameters:

fileName - name of uploading file

contentType - content type of the uploading file

uploadAborted

public void uploadAborted(File file)

Simulates upload interruption by user on browser.

As in the browser, the interrupted file is dropped from the file list and a FileRemovedEvent is fired, freeing a slot when Upload.setMaxFiles(int) is in use.

The file is added and its transfer started in one go, whether or not auto upload is turned off.

Parameters:

file - uploading file

uploadFailed

public void uploadFailed(File file)

Simulates a failure during file upload.

As in the browser, a file whose upload failed stays in the file list.

The file is added and its transfer started in one go, whether or not auto upload is turned off.

Parameters:

file - uploading file

uploadFailed

public void uploadFailed(String fileName,
 String contentType)

Simulates a failure during file upload.

As in the browser, a file whose upload failed stays in the file list.

The file is added and its transfer started in one go, whether or not auto upload is turned off.

Parameters:

fileName - name of uploading file

contentType - content type of the uploading file

removeFile

public void removeFile(String fileName)

Simulates the user removing a file from the upload file list, as if clicking the remove button on the file entry.

A FileRemovedEvent is fired and the file stops counting towards Upload.setMaxFiles(int).

When several entries have the given name, the most recently added one is removed.

Parameters:

fileName - name of the file to remove, as given when it was uploaded

Throws:

IllegalArgumentException - if the file is not in the upload file list

IllegalStateException - if the component is not usable

Since:

25.3

removeFile

public void removeFile(File file)

Simulates the user removing a file from the upload file list, as if clicking the remove button on the file entry.

A FileRemovedEvent is fired and the file stops counting towards Upload.setMaxFiles(int).

When several entries have the name of the given file, the most recently added one is removed.

Parameters:

file - the file to remove

Throws:

IllegalArgumentException - if the file is not in the upload file list

IllegalStateException - if the component is not usable

Since:

25.3

removeFile

public void removeFile(int index)

Simulates the user removing the file at the given position of the upload file list, as if clicking the remove button on that entry. This reaches one entry when several share a name.

A FileRemovedEvent is fired and the file stops counting towards Upload.setMaxFiles(int).

Parameters:

index - the position of the file in the list, in the order getFiles() returns them: the most recently added file first

Throws:

IllegalArgumentException - if there is no file at the position

IllegalStateException - if the component is not usable

startUpload

public void startUpload(String fileName)

Simulates the user clicking the start button of a file that waits in the upload file list because auto upload is turned off, uploading it.

When several waiting entries have the given name, the most recently added one is started.

Parameters:

fileName - name of the file to start, as given when it was added

Throws:

UncheckedIOException - if the upload handler fails to handle the file contents

IllegalArgumentException - if no such file waits in the file list

IllegalStateException - if the component is not usable

startUpload

public void startUpload(File file)

Simulates the user clicking the start button of a file that waits in the upload file list because auto upload is turned off, uploading it.

When several waiting entries have the name of the given file, the most recently added one is started.

Parameters:

file - the file to start

Throws:

UncheckedIOException - if the upload handler fails to handle the file contents

IllegalArgumentException - if no such file waits in the file list

IllegalStateException - if the component is not usable

startUpload

public void startUpload(int index)

Simulates the user clicking the start button of the file at the given position of the upload file list, which waits because auto upload is turned off, uploading it. This reaches one entry when several share a name.

Parameters:

index - the position of the file in the list, in the order getFiles() returns them: the most recently added file first

Throws:

UncheckedIOException - if the upload handler fails to handle the file contents

IllegalArgumentException - if there is no file at the position, or it does not wait to be uploaded

IllegalStateException - if the component is not usable

getFiles

public List<UploadTester.FileStatus> getFiles()

Gets the files the upload file list shows, in the order the browser shows them: the most recently added file first.

A file is UploadTester.UploadStatus.UPLOADED once the upload handler or receiver has consumed it, UploadTester.UploadStatus.FAILED or UploadTester.UploadStatus.REJECTED when its transfer failed or the server refused it, and UploadTester.UploadStatus.PENDING while it waits to be started because auto upload is turned off. Files the client-side constraints refused never enter the list.

Returns:

the files in the upload file list

getLastUploadStatus

public List<UploadTester.FileStatus> getLastUploadStatus()

Returns what happened to each file of the upload last simulated on this component, in the order the files were given, so that a test can check the outcome the same way a user reads the upload file list in the browser.

Files are reported as UploadTester.UploadStatus.UPLOADED once the upload handler or receiver has consumed them, and as UploadTester.UploadStatus.REJECTED both when the client-side gate refused them and when Flow's server-side accepted type validation did, in which case neither shows up as a thrown exception. A file waiting for startUpload(String) because auto upload is turned off is UploadTester.UploadStatus.PENDING; once started, the last upload is that file.

Returns:

the outcome of the last simulated upload, one entry per file, or an empty list if no upload has been simulated yet

Since:

25.3

ensureUploaded

public void ensureUploaded()

Checks that the upload last simulated on this component delivered every one of its files, and fails otherwise.

Convenience for the common case where a test only wants to be sure the files went through: an upload the browser or the server refused is silent, so without this check it would be noticed only later, as a missing side effect.

Throws:

IllegalStateException - if no upload has been simulated on the component, or if any file of the last upload was not uploaded

Since:

25.3

See Also:

• getLastUploadStatus()

ensureUploadFailed

public void ensureUploadFailed()

Checks that at least one file of the upload last simulated on this component failed or was rejected, and fails otherwise.

Counterpart of ensureUploaded() for a test about the failure case, such as an upload handler that throws or a file the component refuses. Use getLastUploadStatus() to check which file failed and why.

A file left UploadTester.UploadStatus.PENDING does not count as failed: it was neither delivered nor refused, such as a file following one whose upload threw or a file waiting because auto upload is turned off.

Throws:

IllegalStateException - if no upload has been simulated on the component, or if no file of the last upload failed or was rejected

See Also:

• getLastUploadStatus()