Skip to content

feat(api): add JSpecify nullability annotations #1970

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Yury Semikhatsky (yury-s) wants to merge 1 commit into
base: main
Choose a base branch
from
Open

feat(api): add JSpecify nullability annotations #1970

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 64 additions & 0 deletions playwright/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,10 @@
<groupId>com.google.code.gson</groupId>
<artifactId>gson</artifactId>
</dependency>
<dependency>
<groupId>org.jspecify</groupId>
<artifactId>jspecify</artifactId>
</dependency>
<dependency>
<groupId>org.java-websocket</groupId>
<artifactId>Java-WebSocket</artifactId>
Expand Down Expand Up @@ -99,4 +103,64 @@
<artifactId>driver-bundle</artifactId>
</dependency>
</dependencies>
<profiles>

@dgozman Dmitry Gozman (dgozman) Sep 3, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I assume this is a test-only null check setup? Otherwise, seems very involved for production pom.

<profile>
<id>nullaway</id>
<activation>
<jdk>[21,)</jdk>
</activation>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<executions>
<execution>
<id>nullaway-testCompile</id>
<phase>test-compile</phase>
<goals>
<goal>testCompile</goal>
</goals>
<configuration>
<fork>true</fork>
<outputDirectory>${project.build.directory}/nullaway-test-classes</outputDirectory>
<testIncludes>
<testInclude>com/microsoft/playwright/nullability/JSpecifyApiConsumer.java</testInclude>
</testIncludes>
<compilerArgs>
<arg>-J--add-exports=jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED</arg>
<arg>-J--add-exports=jdk.compiler/com.sun.tools.javac.file=ALL-UNNAMED</arg>
<arg>-J--add-exports=jdk.compiler/com.sun.tools.javac.main=ALL-UNNAMED</arg>
<arg>-J--add-exports=jdk.compiler/com.sun.tools.javac.model=ALL-UNNAMED</arg>
<arg>-J--add-exports=jdk.compiler/com.sun.tools.javac.parser=ALL-UNNAMED</arg>
<arg>-J--add-exports=jdk.compiler/com.sun.tools.javac.processing=ALL-UNNAMED</arg>
<arg>-J--add-exports=jdk.compiler/com.sun.tools.javac.tree=ALL-UNNAMED</arg>
<arg>-J--add-exports=jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED</arg>
<arg>-J--add-opens=jdk.compiler/com.sun.tools.javac.code=ALL-UNNAMED</arg>
<arg>-J--add-opens=jdk.compiler/com.sun.tools.javac.comp=ALL-UNNAMED</arg>
<arg>-XDcompilePolicy=simple</arg>
<arg>--should-stop=ifError=FLOW</arg>
<arg>-XDaddTypeAnnotationsToSymbol=true</arg>
<arg>-Xplugin:ErrorProne -XepDisableAllChecks -Xep:NullAway:ERROR -XepOpt:NullAway:OnlyNullMarked=true -XepOpt:NullAway:JSpecifyMode=true</arg>
</compilerArgs>
<annotationProcessorPaths>
<path>
<groupId>com.google.errorprone</groupId>
<artifactId>error_prone_core</artifactId>
<version>${error-prone.version}</version>
</path>
<path>
<groupId>com.uber.nullaway</groupId>
<artifactId>nullaway</artifactId>
<version>${nullaway.version}</version>
</path>
</annotationProcessorPaths>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
</profile>
</profiles>
</project>
27 changes: 14 additions & 13 deletions playwright/src/main/java/com/microsoft/playwright/APIRequest.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@

package com.microsoft.playwright;

import org.jspecify.annotations.Nullable;
import com.microsoft.playwright.options.*;
import java.nio.file.Path;
import java.util.*;
Expand All @@ -40,7 +41,7 @@ class NewContextOptions {
* {@code http://localhost:3000/bar.html}</li>
* </ul>
*/
public String baseURL;
public @Nullable String baseURL;
/**
* TLS Client Authentication allows the server to request a client certificate and verify it.
*
Expand All @@ -58,34 +59,34 @@ class NewContextOptions {
* <p> <strong>NOTE:</strong> When using WebKit on macOS, accessing {@code localhost} will not pick up client certificates. You can make it work by
* replacing {@code localhost} with {@code local.playwright}.
*/
public List<ClientCertificate> clientCertificates;
public @Nullable List<ClientCertificate> clientCertificates;
/**
* An object containing additional HTTP headers to be sent with every request. Defaults to none.
*/
public Map<String, String> extraHTTPHeaders;
public @Nullable Map<String, String> extraHTTPHeaders;
/**
* Whether to throw on response codes other than 2xx and 3xx. By default response object is returned for all status codes.
*/
public Boolean failOnStatusCode;
public @Nullable Boolean failOnStatusCode;
/**
* Credentials for <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication">HTTP authentication</a>. If
* no origin is specified, the username and password are sent to any servers upon unauthorized responses.
*/
public HttpCredentials httpCredentials;
public @Nullable HttpCredentials httpCredentials;
/**
* Whether to ignore HTTPS errors when sending network requests. Defaults to {@code false}.
*/
public Boolean ignoreHTTPSErrors;
public @Nullable Boolean ignoreHTTPSErrors;
/**
* Maximum number of request redirects that will be followed automatically. An error will be thrown if the number is
* exceeded. Defaults to {@code 20}. Pass {@code 0} to not follow redirects. This can be overwritten for each request
* individually.
*/
public Integer maxRedirects;
public @Nullable Integer maxRedirects;
/**
* Network proxy settings.
*/
public Proxy proxy;
public @Nullable Proxy proxy;
/**
* Populates context with given storage state. This option can be used to initialize context with logged-in information
* obtained via {@link com.microsoft.playwright.BrowserContext#storageState BrowserContext.storageState()} or {@link
Expand All @@ -94,22 +95,22 @@ class NewContextOptions {
* BrowserContext.storageState()} or {@link com.microsoft.playwright.APIRequestContext#storageState
* APIRequestContext.storageState()} methods.
*/
public String storageState;
public @Nullable String storageState;
/**
* Populates context with given storage state. This option can be used to initialize context with logged-in information
* obtained via {@link com.microsoft.playwright.BrowserContext#storageState BrowserContext.storageState()}. Path to the
* file with saved storage state.
*/
public Path storageStatePath;
public @Nullable Path storageStatePath;
/**
* Maximum time in milliseconds to wait for the response. Defaults to {@code 30000} (30 seconds). Pass {@code 0} to disable
* timeout.
*/
public Double timeout;
public @Nullable Double timeout;
/**
* Specific user agent to use in this context.
*/
public String userAgent;
public @Nullable String userAgent;

/**
* Methods like {@link com.microsoft.playwright.APIRequestContext#get APIRequestContext.get()} take the base URL into
Expand Down Expand Up @@ -257,6 +258,6 @@ default APIRequestContext newContext() {
*
* @since v1.16
*/
APIRequestContext newContext(NewContextOptions options);
APIRequestContext newContext(@Nullable NewContextOptions options);
}

27 changes: 14 additions & 13 deletions playwright/src/main/java/com/microsoft/playwright/APIRequestContext.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@

package com.microsoft.playwright;

import org.jspecify.annotations.Nullable;
import com.microsoft.playwright.options.*;
import java.nio.file.Path;

Expand Down Expand Up @@ -46,7 +47,7 @@ class DisposeOptions {
/**
* The reason to be reported to the operations interrupted by the context disposal.
*/
public String reason;
public @Nullable String reason;

/**
* The reason to be reported to the operations interrupted by the context disposal.
Expand All @@ -60,12 +61,12 @@ class StorageStateOptions {
/**
* Set to {@code true} to include IndexedDB in the storage state snapshot.
*/
public Boolean indexedDB;
public @Nullable Boolean indexedDB;
/**
* The file path to save the storage state to. If {@code path} is a relative path, then it is resolved relative to current
* working directory. If no path is provided, storage state is still returned, but won't be saved to the disk.
*/
public Path path;
public @Nullable Path path;

/**
* Set to {@code true} to include IndexedDB in the storage state snapshot.
Expand Down Expand Up @@ -103,7 +104,7 @@ default APIResponse delete(String url) {
* @param params Optional request parameters.
* @since v1.16
*/
APIResponse delete(String url, RequestOptions params);
APIResponse delete(String url, @Nullable RequestOptions params);
/**
* All responses returned by {@link com.microsoft.playwright.APIRequestContext#get APIRequestContext.get()} and similar
* methods are stored in the memory, so that you can later call {@link com.microsoft.playwright.APIResponse#body
Expand All @@ -123,7 +124,7 @@ default void dispose() {
*
* @since v1.16
*/
void dispose(DisposeOptions options);
void dispose(@Nullable DisposeOptions options);
/**
* Sends HTTP(S) request and returns its response. The method will populate request cookies from the context and update
* context cookies from the response. The method will automatically follow redirects.
Expand Down Expand Up @@ -196,7 +197,7 @@ default APIResponse fetch(String urlOrRequest) {
* @param params Optional request parameters.
* @since v1.16
*/
APIResponse fetch(String urlOrRequest, RequestOptions params);
APIResponse fetch(String urlOrRequest, @Nullable RequestOptions params);
/**
* Sends HTTP(S) request and returns its response. The method will populate request cookies from the context and update
* context cookies from the response. The method will automatically follow redirects.
Expand Down Expand Up @@ -269,7 +270,7 @@ default APIResponse fetch(Request urlOrRequest) {
* @param params Optional request parameters.
* @since v1.16
*/
APIResponse fetch(Request urlOrRequest, RequestOptions params);
APIResponse fetch(Request urlOrRequest, @Nullable RequestOptions params);
/**
* Sends HTTP(S) <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/GET">GET</a> request and returns its
* response. The method will populate request cookies from the context and update context cookies from the response. The
Expand Down Expand Up @@ -308,7 +309,7 @@ default APIResponse get(String url) {
* @param params Optional request parameters.
* @since v1.16
*/
APIResponse get(String url, RequestOptions params);
APIResponse get(String url, @Nullable RequestOptions params);
/**
* Sends HTTP(S) <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/HEAD">HEAD</a> request and returns its
* response. The method will populate request cookies from the context and update context cookies from the response. The
Expand All @@ -329,7 +330,7 @@ default APIResponse head(String url) {
* @param params Optional request parameters.
* @since v1.16
*/
APIResponse head(String url, RequestOptions params);
APIResponse head(String url, @Nullable RequestOptions params);
/**
* Sends HTTP(S) <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PATCH">PATCH</a> request and returns
* its response. The method will populate request cookies from the context and update context cookies from the response.
Expand All @@ -350,7 +351,7 @@ default APIResponse patch(String url) {
* @param params Optional request parameters.
* @since v1.16
*/
APIResponse patch(String url, RequestOptions params);
APIResponse patch(String url, @Nullable RequestOptions params);
/**
* Sends HTTP(S) <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST">POST</a> request and returns its
* response. The method will populate request cookies from the context and update context cookies from the response. The
Expand Down Expand Up @@ -445,7 +446,7 @@ default APIResponse post(String url) {
* @param params Optional request parameters.
* @since v1.16
*/
APIResponse post(String url, RequestOptions params);
APIResponse post(String url, @Nullable RequestOptions params);
/**
* Sends HTTP(S) <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PUT">PUT</a> request and returns its
* response. The method will populate request cookies from the context and update context cookies from the response. The
Expand All @@ -466,7 +467,7 @@ default APIResponse put(String url) {
* @param params Optional request parameters.
* @since v1.16
*/
APIResponse put(String url, RequestOptions params);
APIResponse put(String url, @Nullable RequestOptions params);
/**
* Returns storage state for this request context, contains current cookies and local storage snapshot if it was passed to
* the constructor.
Expand All @@ -482,7 +483,7 @@ default String storageState() {
*
* @since v1.16
*/
String storageState(StorageStateOptions options);
String storageState(@Nullable StorageStateOptions options);
/**
*
*
Expand Down
5 changes: 3 additions & 2 deletions playwright/src/main/java/com/microsoft/playwright/APIResponse.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@

package com.microsoft.playwright;

import org.jspecify.annotations.Nullable;
import com.microsoft.playwright.options.*;
import java.util.*;

Expand Down Expand Up @@ -61,14 +62,14 @@ public interface APIResponse {
*
* @since v1.61
*/
SecurityDetails securityDetails();
@Nullable SecurityDetails securityDetails();
/**
* Returns the IP address and port of the server. Resolves to {@code null} if the server address is not available. For
* redirected requests, returns the information for the last request in the redirect chain.
*
* @since v1.61
*/
ServerAddr serverAddr();
@Nullable ServerAddr serverAddr();
/**
* Contains the status code of the response (e.g., 200 for a success).
*
Expand Down
Loading