Add WebDriver-compatible API (OpenAPI + server stubs + Swagger UI)

[Copilot]

Adds a WebDriver-compatible HTTP API with selector-first extensions. Includes OpenAPI 3.1 spec, Spring Boot controllers with in-memory mock storage, and Swagger UI integration.

API Endpoints

Session: POST/GET/DELETE /session/{sessionId}

Navigation: /session/{sessionId}/url, /documentUri, /baseUri

Selector-first extensions:

• /session/{sessionId}/selectors/exists, /waitFor, /element, /elements
• /session/{sessionId}/selectors/click, /fill, /press, /outerHtml, /screenshot

Standard WebDriver: /element, /elements, /element/{id}/click, /value, /attribute/{name}, /text

Script execution: /execute/sync, /execute/async

Control: /control/delay, /pause, /stop

Events: /event-configs, /events, /events/subscribe

Files Added

• openapi/openapi.yaml – OpenAPI 3.1 spec
• pulsar-rest/src/main/kotlin/.../dto/ApiDtos.kt – Request/response DTOs
• pulsar-rest/src/main/kotlin/.../store/InMemoryStore.kt – Mock session/element storage
• pulsar-rest/src/main/kotlin/.../webdriver/*.kt – 7 controllers
• pulsar-rest/src/main/kotlin/.../config/OpenApiConfig.kt – SpringDoc config
• Integration tests with MockMvc

Dependencies

• springdoc-openapi-starter-webmvc-ui:2.6.0 (compatible with Spring Boot 3.3.x)
• jackson-module-kotlin

Usage

# Create session
curl -X POST localhost:8182/session -H "Content-Type: application/json" \
  -d '{"capabilities": {"browserName": "chrome"}}'

# Click by selector
curl -X POST localhost:8182/session/{id}/selectors/click \
  -H "Content-Type: application/json" -d '{"selector": "button.submit"}'

Swagger UI: http://localhost:8182/swagger-ui.html

Limitations

Mock implementation only—no real browser integration. All selector operations return success, screenshots return 1x1 PNG placeholder.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• https://api.github.com//advisories
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node /home/REDACTED/work/_temp/ghcca-node/node/bin/node --enable-source-maps /home/REDACTED/work/_temp/copilot-developer-action-main/dist/index.js (http block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

Create a new branch named feature/openapi-webdriver-api based on master in the platonai/Browser4 repository and open a pull request that adds a WebDriver-compatible HTTP API (selector-first extensions) with OpenAPI spec and a Spring Boot Kotlin server skeleton.

Requirements / Deliverables:

1. Add OpenAPI spec file at openapi/openapi.yaml matching the previously prepared OpenAPI 3.1 skeleton (paths and components for session, navigation, selectors, element, interactions, screenshot, execute, control, events). Expose the file at /openapi.yaml in the server.

2. Add a new module pulsar-rest (or reuse existing pulsar-rest module if present) with a Spring Boot Kotlin app containing minimal, in-memory mock implementations:

   • PulsarRestApplication.kt (SpringBootApplication)
   • InMemoryStore.kt for sessions, elements, event-configs, subscriptions
   • DTOs in pulsar-rest/src/main/kotlin/ai/platon/pulsar/rest/api/dto/ApiDtos.kt for NewSessionRequest/Response, SetUrlRequest, SelectorRef, ElementRef, EventConfig, Event, ErrorResponse, and other needed types. Types should map to OpenAPI schemas.
   • Controllers with endpoints and behavior:
     • SessionController: POST /session, DELETE /session/{sessionId}, GET /session/{sessionId}
     • NavigationController: POST /session/{sessionId}/url, GET /session/{sessionId}/url, GET /session/{sessionId}/documentUri, GET /session/{sessionId}/baseUri
     • SelectorController: POST /session/{sessionId}/selectors/exists, /waitFor, /element, /elements, /click, /fill, /press, /outerHtml, /screenshot
     • ElementController: POST /session/{sessionId}/element, /elements; POST /session/{sessionId}/element/{elementId}/click and /value; GET /session/{sessionId}/element/{elementId}/attribute/{name} and /text
     • ScriptController: POST /session/{sessionId}/execute/sync and /async
     • ControlController: POST /session/{sessionId}/control/delay, /pause, /stop
     • EventsController: POST/GET /session/{sessionId}/event-configs, GET /session/{sessionId}/events, POST /session/{sessionId}/events/subscribe
   • Implement basic request validation and return WebDriver-style JSON wrapped responses { "value": ... } matching openapi. Use InMemoryStore to persist session and element mocks. For selector endpoints generate elementId by hashing selector string and return ElementRef accordingly.

3. Integrate springdoc-openapi UI to provide Swagger UI. Add dependency org.springdoc:springdoc-openapi-ui in pulsar-rest/pom.xml and configure to serve Swagger UI at /swagger-ui.html. Make sure /openapi.yaml is accessible (serve from resources/static or controller endpoint).

4. Update pulsar-rest/pom.xml to include spring-boot-starter-web, jackson-module-kotlin, springdoc-openapi-ui, spring-boot-starter-test dependencies as needed. Keep versions compatible with repository parent POM. Make minimal changes outside pulsar-rest and openapi/.

5. Add basic integration tests in pulsar-rest/src/test/kotlin/... using SpringBootTest and TestRestTemplate or MockMvc: tests should create a session, call POST /session/{id}/url, call selectors/exists and /selectors/element, asserting 200 responses and verifying the returned JSON shape contains expected keys (sessionId, value.exists or element reference).

6. CI and build: Ensure module builds. If build or dependency conflicts block implementation, stop and report the blocking error in the PR description and do not merge.

7. PR details: Open a PR from feature/openapi-webdriver-api into master with title 'Add WebDriver-compatible API (OpenAPI + server stubs + Swagger UI)'. PR body must include:

   • Summary of implemented endpoints, files added, and mock behavior limitations (no real browser integration yet).
   • How to run tests and start the server.
   • Example curl commands for create session, navigate, selectors/exists and selectors/click.
   • Any blockers or known issues.

Constraints:

• Keep changes isolated to pulsar-rest and openapi/ files; do not change other modules.
• Ensure code is Kotlin idiomatic and logs incoming requests at debug level. Add X-Request-Id header in responses when feasible.
• Maintain WebDriver response wrapping { "value": ... } to stay compatible.

If any required module or build constraint prevents creating the pulsar-rest module, stop and report the blocking issue in the PR. If successful, provide the PR URL and list of changed files.

Do not merge the PR. Create it in an open state for review.

Repository: platonai/Browser4

This pull request was created as a result of the following prompt from Copilot chat.

Create a new branch named feature/openapi-webdriver-api based on master in the platonai/Browser4 repository and open a pull request that adds a WebDriver-compatible HTTP API (selector-first extensions) with OpenAPI spec and a Spring Boot Kotlin server skeleton.

Requirements / Deliverables:

1. Add OpenAPI spec file at openapi/openapi.yaml matching the previously prepared OpenAPI 3.1 skeleton (paths and components for session, navigation, selectors, element, interactions, screenshot, execute, control, events). Expose the file at /openapi.yaml in the server.

2. Add a new module pulsar-rest (or reuse existing pulsar-rest module if present) with a Spring Boot Kotlin app containing minimal, in-memory mock implementations:

   • PulsarRestApplication.kt (SpringBootApplication)
   • InMemoryStore.kt for sessions, elements, event-configs, subscriptions
   • DTOs in pulsar-rest/src/main/kotlin/ai/platon/pulsar/rest/api/dto/ApiDtos.kt for NewSessionRequest/Response, SetUrlRequest, SelectorRef, ElementRef, EventConfig, Event, ErrorResponse, and other needed types. Types should map to OpenAPI schemas.
   • Controllers with endpoints and behavior:
     • SessionController: POST /session, DELETE /session/{sessionId}, GET /session/{sessionId}
     • NavigationController: POST /session/{sessionId}/url, GET /session/{sessionId}/url, GET /session/{sessionId}/documentUri, GET /session/{sessionId}/baseUri
     • SelectorController: POST /session/{sessionId}/selectors/exists, /waitFor, /element, /elements, /click, /fill, /press, /outerHtml, /screenshot
     • ElementController: POST /session/{sessionId}/element, /elements; POST /session/{sessionId}/element/{elementId}/click and /value; GET /session/{sessionId}/element/{elementId}/attribute/{name} and /text
     • ScriptController: POST /session/{sessionId}/execute/sync and /async
     • ControlController: POST /session/{sessionId}/control/delay, /pause, /stop
     • EventsController: POST/GET /session/{sessionId}/event-configs, GET /session/{sessionId}/events, POST /session/{sessionId}/events/subscribe
   • Implement basic request validation and return WebDriver-style JSON wrapped responses { "value": ... } matching openapi. Use InMemoryStore to persist session and element mocks. For selector endpoints generate elementId by hashing selector string and return ElementRef accordingly.

3. Integrate springdoc-openapi UI to provide Swagger UI. Add dependency org.springdoc:springdoc-openapi-ui in pulsar-rest/pom.xml and configure to serve Swagger UI at /swagger-ui.html. Make sure /openapi.yaml is accessible (serve from resources/static or controller endpoint).

4. Update pulsar-rest/pom.xml to include spring-boot-starter-web, jackson-module-kotlin, springdoc-openapi-ui, spring-boot-starter-test dependencies as needed. Keep versions compatible with repository parent POM. Make minimal changes outside pulsar-rest and openapi/.

5. Add basic integration tests in pulsar-rest/src/test/kotlin/... using SpringBootTest and TestRestTemplate or MockMvc: tests should create a session, call POST /session/{id}/url, call selectors/exists and /selectors/element, asserting 200 responses and verifying the returned JSON shape contains expected keys (sessionId, value.exists or element reference).

6. CI and build: Ensure module builds. If build or dependency conflicts block implementation, stop and report the blocking error in the PR description and do not merge.

7. PR details: Open a PR from feature/openapi-webdriver-api into master with title 'Add WebDriver-compatible API (OpenAPI + server stubs + Swagger UI)'. PR body must include:

   • Summary of implemented endpoints, files added, and mock behavior limitations (no real browser integration yet).
   • How to run tests and start the server.
   • Example curl commands for create session, navigate, selectors/exists and selectors/click.
   • Any blockers or known issues.

Constraints:

• Keep changes isolated to pulsar-rest and openapi/ files; do not change other modules.
• Ensure code is Kotlin idiomatic and logs incoming requests at debug level. Add X-Request-Id header in responses when feasible.
• Maintain WebDriver response wrapping { "value": ... } to stay compatible.

If any required module or build constraint prevents creating the pulsar-rest module, stop and report the blocking issue in the PR. If successful, provide the PR URL and list of changed files.

Do not merge the PR. Create it in an open state for review.

Repository: platonai/Browser4

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.