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.

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.
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(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	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

canSetValueAsUser, clearAsUser, clickClearButtonAsUser, ensureComponentIsUsable, ensureComponentIsUsable, ensureComponentIsUsableOrDetach, ensureVisible, ensureVisible, find, findAllByQuery, findByQuery, fireDomEvent, fireDomEvent, fireDomEvent, getComponent, getField, getField, getMethod, getMethod, isComponentReadOnly, 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.

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.

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.

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.

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.

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.

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.

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.

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.

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).

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

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).

Parameters:

file - the file to remove

Throws:

IllegalArgumentException - if the file is not 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.

Returns:

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

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

See Also:

• getLastUploadStatus()