From 0fc72861baa14eb43e65df1be7b7fa07d28cffd2 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Tue, 27 Jan 2026 09:06:35 +0000 Subject: [PATCH] Add AI agent documentation and skills Added AGENTS.md, CLAUDE.md, and GEMINI.md to provide context and guidelines for AI agents working on the repository. Created .antigravity/skills.yaml to define skills for running tests and generating new Playwright test classes (including Spring integration). These files include best practices for Java, Playwright, JUnit 5, and Spring, specifically focusing on anti-bot detection and robust locator strategies. Co-authored-by: alstafeev <18335072+alstafeev@users.noreply.github.com> --- .antigravity/skills.yaml | 129 +++++++++++++++++++++++++++++++++++++++ AGENTS.md | 47 ++++++++++++++ CLAUDE.md | 28 +++++++++ GEMINI.md | 30 +++++++++ 4 files changed, 234 insertions(+) create mode 100644 .antigravity/skills.yaml create mode 100644 AGENTS.md create mode 100644 CLAUDE.md create mode 100644 GEMINI.md diff --git a/.antigravity/skills.yaml b/.antigravity/skills.yaml new file mode 100644 index 0000000..41bf3c7 --- /dev/null +++ b/.antigravity/skills.yaml @@ -0,0 +1,129 @@ +skills: + - name: run-tests + description: Run all automated tests in the project using Maven. + command: mvn test + + - name: run-single-test + description: Run a specific test class. + command: mvn test -Dtest={{test_class}} + arguments: + - name: test_class + description: The name of the test class to run (e.g., GoogleTest). + required: true + + - name: add-playwright-test + description: Create a new Playwright test class with standard setup (anti-bot, headless). + content: | + package com.example; + + import com.microsoft.playwright.*; + import org.junit.jupiter.api.*; + import java.util.List; + import static org.junit.jupiter.api.Assertions.*; + + public class {{ClassName}} { + static Playwright playwright; + static Browser browser; + BrowserContext context; + Page page; + + @BeforeAll + static void launchBrowser() { + playwright = Playwright.create(); + browser = playwright.chromium().launch(new BrowserType.LaunchOptions() + .setHeadless(true) + .setArgs(List.of( + "--disable-blink-features=AutomationControlled", + "--no-sandbox", + "--disable-setuid-sandbox" + ))); + } + + @AfterAll + static void closeBrowser() { + playwright.close(); + } + + @BeforeEach + void createContextAndPage() { + context = browser.newContext(new Browser.NewContextOptions() + .setUserAgent("Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36")); + page = context.newPage(); + page.addInitScript("Object.defineProperty(navigator, 'webdriver', {get: () => undefined})"); + } + + @AfterEach + void closeContext() { + context.close(); + } + + @Test + void exampleTest() { + page.navigate("https://example.com"); + assertTrue(page.title().contains("Example")); + } + } + + - name: add-spring-playwright-test + description: Create a new Playwright test class integrated with Spring Boot (requires spring-boot-starter-test). + content: | + package com.example; + + import com.microsoft.playwright.*; + import org.junit.jupiter.api.*; + import org.springframework.beans.factory.annotation.Autowired; + import org.springframework.boot.test.context.SpringBootTest; + import java.util.List; + import static org.junit.jupiter.api.Assertions.*; + + @SpringBootTest + public class {{ClassName}} { + + // Assuming a Bean for Playwright/Browser is configured in a TestConfiguration + // If not, you can initialize it in @BeforeAll as in standard tests. + + static Playwright playwright; + static Browser browser; + BrowserContext context; + Page page; + + @BeforeAll + static void launchBrowser() { + playwright = Playwright.create(); + browser = playwright.chromium().launch(new BrowserType.LaunchOptions() + .setHeadless(true) + .setArgs(List.of( + "--disable-blink-features=AutomationControlled", + "--no-sandbox", + "--disable-setuid-sandbox" + ))); + } + + @AfterAll + static void closeBrowser() { + playwright.close(); + } + + @BeforeEach + void createContextAndPage() { + context = browser.newContext(new Browser.NewContextOptions() + .setUserAgent("Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36")); + page = context.newPage(); + page.addInitScript("Object.defineProperty(navigator, 'webdriver', {get: () => undefined})"); + } + + @Test + void springTest() { + // Use Autowired components here if needed + page.navigate("https://example.com"); + assertTrue(page.title().contains("Example")); + } + } + + - name: debug-test + description: Instructions for debugging a failed test. + content: | + 1. Enable headful mode in the test setup: `.setHeadless(false)`. + 2. Increase timeout: `page.setDefaultTimeout(10000);`. + 3. Use `page.pause()` to inspect the browser state during execution. + 4. Check `target/screenshots` if screenshot capture is enabled. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..bd2943f --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,47 @@ +# Agent Guidelines + +## Project Overview +This is a Java-based automated testing repository designed for reliability and resilience. +- **Language**: Java 17 +- **Build Tool**: Maven +- **Automation Framework**: Playwright (Java) +- **Test Runner**: JUnit 5 +- **Dependency Injection**: Spring Framework (Spring Boot Test) + +## Key Directives + +### 1. Bot Detection Evasion +When initializing Playwright browsers, you **must** configure them to avoid detection by anti-bot systems. +- **Headless Mode**: Tests usually run headless, but `headless` mode can sometimes trigger bot checks. +- **Arguments**: Always include the following args in `LaunchOptions`: + ```java + .setArgs(List.of( + "--disable-blink-features=AutomationControlled", + "--no-sandbox", + "--disable-setuid-sandbox" + )) + ``` +- **User Agent**: Use a real, modern User-Agent string in `Browser.NewContextOptions`. +- **Navigator Property**: Mask the webdriver property in an init script: + ```java + page.addInitScript("Object.defineProperty(navigator, 'webdriver', {get: () => undefined})"); + ``` + +### 2. Spring Integration +- **Page Objects**: Define Page Objects as Spring Components (`@Component`) to leverage dependency injection. +- **Test Classes**: Use `@SpringBootTest` (or `@ExtendWith(SpringExtension.class)`) to load the context. +- **Browser Management**: Prefer managing the `Browser` or `Playwright` instance as a Bean to share it efficiently or scoped beans for parallelism. + +### 3. Code Style & Structure +- **Page Object Model**: Use the Page Object Model (POM) pattern for larger tests to separate logic from selectors. +- **Locators**: Prefer user-facing locators (`getByRole`, `getByText`, `getByLabel`) over CSS/XPath where possible to improve resilience. +- **Cleanup**: Always ensure `browser.close()` and `playwright.close()` are called, typically in `@AfterAll` or `@AfterEach`. + +### 4. Debugging & Artifacts +- **Screenshots**: Implement screenshot capture on failure (or for every test) in `@AfterEach`. +- **Tracing**: Consider enabling Playwright Tracing for complex failures. + +## Common Commands +- **Run All Tests**: `mvn test` +- **Run Single Test Class**: `mvn test -Dtest=TestClassName` +- **Run Specific Test Method**: `mvn test -Dtest=TestClassName#methodName` diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..8abe841 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,28 @@ +# Claude Context for Playwright Java Project + +## Build & Test Commands +- **Build**: `mvn clean compile` +- **Test All**: `mvn test` +- **Test Single Class**: `mvn test -Dtest={TestClassName}` +- **Test Single Method**: `mvn test -Dtest={TestClassName}#{methodName}` +- **Package**: `mvn package -DskipTests` + +## Project Structure +- `src/test/java`: Contains all test code and Page Objects. +- `src/main/java`: May contain shared utilities or Spring configuration. +- `pom.xml`: Project dependencies (Playwright, JUnit 5, Spring Boot Starter Test). + +## Code Style Guidelines +- **Java Version**: 17 +- **Naming**: PascalCase for classes, camelCase for methods/variables. +- **Assertions**: Use `org.junit.jupiter.api.Assertions`. +- **Spring**: Use `@Autowired` for injecting Page Objects. Use `@Component` for Page Object classes. +- **Playwright**: + - Use `Locator` API instead of `ElementHandle`. + - Use `Page.getByRole()` and `Page.getByText()` for robust selection. + - Handle asynchronous operations naturally (Playwright auto-waits). + +## Common Patterns +- **Setup**: `@BeforeAll` for Browser/Playwright launch, `@BeforeEach` for Context/Page creation. +- **Teardown**: `@AfterEach` for Page/Context close (and screenshots), `@AfterAll` for Browser/Playwright close. +- **Anti-Bot**: Always use headers and args to look like a real browser (see `AGENTS.md`). diff --git a/GEMINI.md b/GEMINI.md new file mode 100644 index 0000000..348c73c --- /dev/null +++ b/GEMINI.md @@ -0,0 +1,30 @@ +# Gemini Context + +## Project Identification +**Type**: Java Automated Testing Repository +**Tech Stack**: Java 17, Maven, Playwright 1.41+, JUnit 5, Spring Framework (Test) + +## Operational Guidelines + +### 1. Test Execution +- Run tests using Maven: `mvn test` +- All tests are located in `src/test/java`. + +### 2. Coding Standards +- **Imports**: Avoid wildcard imports if possible. +- **Spring**: Leverage Spring's Dependency Injection for managing Page Objects and configuration. +- **Playwright Usage**: + - Always use `Playwright.create()` to initialize. + - Use `BrowserContext` to isolate tests (cookies, storage). + - Use `Locator` for all interactions. Avoid `ElementHandle`. + +### 3. Constraints & Security +- **Dependencies**: Do NOT add new dependencies to `pom.xml` unless explicitly requested. +- **Bot Protection**: This project interacts with sites that have bot protections (e.g., Google). You MUST ensure the browser is launched with specific arguments to evade detection. + - `--disable-blink-features=AutomationControlled` + - `--no-sandbox` +- **Resource Management**: Leakage of browser processes is critical. Ensure `close()` is called in `finally` blocks or `@After...` annotations. + +## Repository Map +- `src/test/java/com/example/`: Root for test packages. +- `target/`: Build artifacts and screenshots (do not commit).