docs: junit fixture javadocs (#1510)

Reference #1369

Author: yury-s

playwright/src/main/java/com/microsoft/playwright/junit/Options.java

@@ -21,6 +21,15 @@
 import com.microsoft.playwright.BrowserType;
 import com.microsoft.playwright.Playwright;
 
+/**
+ * <strong>NOTE:</strong> this API is experimental and is subject to changes.
+ *
+ * <p> Instances of this class are expected to be created by custom {@link OptionsFactory}
+ * implementations. Implement custom factories to provide custom Playwright configurations.
+ *
+ * <p> For more details and usage examples see our
+ * <a href="https://playwright.dev/java/docs/junit">JUnit guide</a>.
+ */
 public class Options {
   public String baseUrl;
   public String channel;

playwright/src/main/java/com/microsoft/playwright/junit/OptionsFactory.java

@@ -16,6 +16,47 @@
 
 package com.microsoft.playwright.junit;
 
+/**
+ * <strong>NOTE:</strong> this API is experimental and is subject to changes.
+ *
+ * <p> Implement this interface to pass custom options to {@link UsePlaywright}
+ * annotation.
+ *
+ * <p> An example of implementing {@code @OptionsFactory}:
+ * <pre>{@code
+ * import com.microsoft.playwright.junit.Options;
+ * import com.microsoft.playwright.junit.OptionsFactory;
+ * import com.microsoft.playwright.junit.UsePlaywright;
+ *
+ * @UsePlaywright(MyTest.CustomOptions.class)
+ * public class MyTest {
+ *
+ *   public static class CustomOptions implements OptionsFactory {
+ *     @Override
+ *     public Options getOptions() {
+ *       return new Options()
+ *           .setHeadless(false)
+ *           .setContextOption(new Browser.NewContextOptions()
+ *               .setBaseURL("https://github.com"))
+ *           .setApiRequestOptions(new APIRequest.NewContextOptions()
+ *               .setBaseURL("https://playwright.dev"));
+ *     }
+ *   }
+ *
+ *   @Test
+ *   public void testWithCustomOptions(Page page, APIRequestContext request) {
+ *     page.navigate("/");
+ *     assertThat(page).hasURL(Pattern.compile("github"));
+ *
+ *     APIResponse response = request.get("/");
+ *     assertTrue(response.text().contains("Playwright"));
+ *   }
+ * }
+ * }</pre>
+ *
+ * <p>For more details and usage examples see our
+ * <a href="https://playwright.dev/java/docs/junit">JUnit guide</a>.
+ */
 public interface OptionsFactory {
   Options getOptions();
 }

playwright/src/main/java/com/microsoft/playwright/junit/UsePlaywright.java

@@ -16,6 +16,7 @@
 
 package com.microsoft.playwright.junit;
 
+import com.microsoft.playwright.Browser;
 import com.microsoft.playwright.junit.impl.*;
 import org.junit.jupiter.api.extension.ExtendWith;
 
@@ -24,6 +25,57 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * <strong>NOTE:</strong> this API is experimental and is subject to changes.
+ *
+ * Use {@code @UsePlaywright} annotation to automatically manage Playwright objects
+ * used in your test. Custom configuration can be provided by implementing
+ * {@link OptionsFactory} and passing the class as a parameter.
+ *
+ * <p> When a test class is annotated with {@code @UsePlaywright} each test method can
+ * use any of the following arguments that will be automatically created at run time:
+ * <ul>
+ * <li> {@link com.microsoft.playwright.Page Page page}</li>
+ * <li> {@link com.microsoft.playwright.BrowserContext BrowserContext context}</li>
+ * <li> {@link com.microsoft.playwright.Browser Browser browser}</li>
+ * <li> {@link com.microsoft.playwright.APIRequestContext APIRequestContext request}</li>
+ * <li> {@link com.microsoft.playwright.Playwright Playwright playwright}</li>
+ * </ul>
+ * {@code Page} and {@code BrowserContext} are created before each test and closed
+ * after the test has finished. {@code Browser} and {@code Playwright} are reused
+ * between tests for better efficiency.
+ *
+ * <p> An example of using {@code @UsePlaywright} annotation:
+ * <pre>{@code
+ * import com.microsoft.playwright.Browser;
+ * import com.microsoft.playwright.BrowserContext;
+ * import com.microsoft.playwright.Page;
+ * import org.junit.jupiter.api.Test;
+ *
+ * import static com.microsoft.playwright.assertions.PlaywrightAssertions.assertThat;
+ * import static org.junit.jupiter.api.Assertions.assertEquals;
+ * import static org.junit.jupiter.api.Assertions.assertNotNull;
+ *
+ * @UsePlaywright
+ * public class TestExample {
+ *   @Test
+ *   void shouldProvidePage(Page page) {
+ *     page.navigate("https://playwright.dev");
+ *     assertThat(page).hasURL("https://playwright.dev/");
+ *   }
+ *
+ *   @Test
+ *   void shouldResolvePlaywrightObjects(Page page, BrowserContext context, Browser browser) {
+ *     assertEquals(context, page.context());
+ *     assertEquals(browser, context.browser());
+ *     assertNotNull(browser.version());
+ *   }
+ * }
+ * }</pre>
+ *
+ * <p> For more details and usage examples see our
+ * <a href="https://playwright.dev/java/docs/junit">JUnit guide</a>.
+ */
 @ExtendWith({OptionsExtension.class, PlaywrightExtension.class, BrowserExtension.class, BrowserContextExtension.class,
              PageExtension.class, APIRequestContextExtension.class})
 @Retention(RetentionPolicy.RUNTIME)