feat: added support for CDPSession (#128)

Author: jiong-han

Diff for: browser.go

@@ -52,6 +52,19 @@ func (b *browserImpl) NewPage(options ...BrowserNewContextOptions) (Page, error)
 	return page, nil
 }
 
+func (b *browserImpl) NewBrowserCDPSession() (CDPSession, error) {
+	channel, err := b.channel.Send("crNewBrowserCDPSession", map[string]interface{}{
+		"sdkLanguage": "javascript",
+	})
+	if err != nil {
+		return nil, fmt.Errorf("could not send message: %w", err)
+	}
+
+	cdpSession := fromChannel(channel).(*cdpSessionImpl)
+
+	return cdpSession, nil
+}
+
 func (b *browserImpl) Contexts() []BrowserContext {
 	b.Lock()
 	defer b.Unlock()

Diff for: browser_context.go

@@ -46,6 +46,20 @@ func (b *browserContextImpl) Browser() Browser {
 	return b.browser
 }
 
+func (b *browserContextImpl) NewCDPSession(page Page) (CDPSession, error) {
+	channel, err := b.channel.Send("crNewCDPSession", map[string]interface{}{
+		"sdkLanguage": "javascript",
+		"page":        page.(*pageImpl).channel,
+	})
+	if err != nil {
+		return nil, fmt.Errorf("could not send message: %w", err)
+	}
+
+	cdpSession := fromChannel(channel).(*cdpSessionImpl)
+
+	return cdpSession, nil
+}
+
 func (b *browserContextImpl) NewPage(options ...BrowserNewPageOptions) (Page, error) {
 	if b.ownedPage != nil {
 		return nil, errors.New("Please use browser.NewContext()")

Diff for: cdp_session.go

@@ -0,0 +1,38 @@
+package playwright
+
+type cdpSessionImpl struct {
+	channelOwner
+}
+
+func (c *cdpSessionImpl) Detach() error {
+	_, err := c.channel.Send("detach")
+	return err
+}
+
+func (c *cdpSessionImpl) Send(method string, params map[string]interface{}) (interface{}, error) {
+	result, err := c.channel.Send("send", map[string]interface{}{
+		"method": method,
+		"params": params,
+	})
+	if err != nil {
+		return nil, err
+	}
+
+	return result, err
+}
+
+func (c *cdpSessionImpl) onEvent(params map[string]interface{}) {
+	c.Emit(params["method"].(string), params["params"])
+}
+
+func newCDPSession(parent *channelOwner, objectType string, guid string, initializer map[string]interface{}) *cdpSessionImpl {
+	bt := &cdpSessionImpl{}
+
+	bt.createChannelOwner(bt, parent, objectType, guid, initializer)
+
+	bt.channel.On("event", func(params map[string]interface{}) {
+		bt.onEvent(params)
+	})
+
+	return bt
+}

Diff for: generated_interfaces.go

@@ -24,10 +24,27 @@ type Browser interface {
 	// testing frameworks should explicitly create Browser.newContext() followed by the
 	// BrowserContext.newPage() to control their exact life times.
 	NewPage(options ...BrowserNewContextOptions) (Page, error)
+	NewBrowserCDPSession() (CDPSession, error)
 	// Returns the browser version.
 	Version() string
 }
 
+// The `CDPSession` instances are used to talk raw Chrome Devtools Protocol:
+// - protocol methods can be called with `session.send` method.
+// - protocol events can be subscribed to with `session.on` method.
+// Useful links:
+// - Documentation on DevTools Protocol can be found here:
+// [DevTools Protocol Viewer](https://chromedevtools.github.io/devtools-protocol/).
+// - Getting Started with DevTools Protocol:
+// https://github.com/aslushnikov/getting-started-with-cdp/blob/master/README.md
+type CDPSession interface {
+	EventEmitter
+	// Detaches the CDPSession from the target. Once detached, the CDPSession object won't emit any events and can't be used to
+	// send messages.
+	Detach() error
+	Send(method string, params map[string]interface{}) (interface{}, error)
+}
+
 // BrowserContexts provide a way to operate multiple independent browser sessions.
 // If a page opens another page, e.g. with a `window.open` call, the popup will belong to the parent page's browser
 // context.
@@ -79,6 +96,7 @@ type BrowserContext interface {
 	// Grants specified permissions to the browser context. Only grants corresponding permissions to the given origin if
 	// specified.
 	GrantPermissions(permissions []string, options ...BrowserContextGrantPermissionsOptions) error
+	NewCDPSession(page Page) (CDPSession, error)
 	// Creates a new page in the browser context.
 	NewPage(options ...BrowserNewPageOptions) (Page, error)
 	// Returns all open pages in the context.

Diff for: objectFactory.go

@@ -12,6 +12,8 @@ func createObjectFactory(parent *channelOwner, objectType string, guid string, i
 		return newBrowserType(parent, objectType, guid, initializer)
 	case "BrowserContext":
 		return newBrowserContext(parent, objectType, guid, initializer)
+	case "CDPSession":
+		return newCDPSession(parent, objectType, guid, initializer)
 	case "ConsoleMessage":
 		return newConsoleMessage(parent, objectType, guid, initializer)
 	case "Dialog":

Diff for: scripts/data/interfaces.json

@@ -29,11 +29,28 @@
 			"options ...BrowserNewContextOptions",
 			"(Page, error)"
 		],
+		"NewBrowserCDPSession": [
+			null,
+			"(CDPSession, error)"
+		],
 		"Version": [
 			null,
 			"string"
 		]
 	},
+	"CDPSession": {
+		"extends": [
+			"EventEmitter"
+		],
+		"Detach": [
+			null,
+			"error"
+		],
+		"Send": [
+			"method string, params map[string]interface{}",
+			"(interface{}, error)"
+		]
+	},
 	"BrowserContext": {
 		"extends": [
 			"EventEmitter"
@@ -82,6 +99,10 @@
 			"permissions []string, options ...BrowserContextGrantPermissionsOptions",
 			"error"
 		],
+		"NewCDPSession": [
+			"page Page",
+			"(CDPSession, error)"
+		],	
 		"NewPage": [
 			"options ...BrowserNewPageOptions",
 			"(Page, error)"

Diff for: scripts/validate-interfaces.js

@@ -5,7 +5,6 @@ const api = getAPIDocs()
 
 const IGNORE_CLASSES = [
   "Selectors",
-  "CDPSession",
   "Logger",
   "BrowserServer",
   "Accessibility",

Diff for: tests/browser_context_test.go

@@ -77,6 +77,18 @@ func TestBrowserContextSetExtraHTTPHeaders(t *testing.T) {
 	<-intercepted
 }
 
+func TestBrowserContextNewCDPSession(t *testing.T) {
+	BeforeEach(t)
+	defer AfterEach(t)
+	cdpSession, err := page.Context().NewCDPSession(page)
+	if isChromium {
+		require.NoError(t, err)
+		require.NoError(t, cdpSession.Detach())
+	} else {
+		require.Error(t, err)
+	}
+}
+
 func TestBrowserContextSetGeolocation(t *testing.T) {
 	BeforeEach(t)
 	defer AfterEach(t)

Diff for: tests/browser_test.go

@@ -100,6 +100,18 @@ func TestBrowserShouldErrorUponSecondCreateNewPage(t *testing.T) {
 	require.NoError(t, page.Close())
 }
 
+func TestNewBrowserCDPSession(t *testing.T) {
+	BeforeEach(t)
+	defer AfterEach(t)
+	cdpSession, err := browser.NewBrowserCDPSession()
+	if isChromium {
+		require.NoError(t, err)
+		require.NoError(t, cdpSession.Detach())
+	} else {
+		require.Error(t, err)
+	}
+}
+
 func TestBrowserClose(t *testing.T) {
 	pw, err := playwright.Run()
 	require.NoError(t, err)

Diff for: tests/cdp_session_test.go

@@ -0,0 +1,53 @@
+package playwright_test
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestCDPSessionSend(t *testing.T) {
+	BeforeEach(t)
+	defer AfterEach(t)
+	cdpSession, err := browser.NewBrowserCDPSession()
+	if isChromium {
+		require.NoError(t, err)
+		result, err := cdpSession.Send("Target.getTargets", nil)
+		require.NoError(t, err)
+		targetInfos := result.(map[string]interface{})["targetInfos"].([]interface{})
+		require.Equal(t, 1, len(targetInfos))
+	} else {
+		require.Error(t, err)
+	}
+}
+
+func TestCDPSessionOn(t *testing.T) {
+	BeforeEach(t)
+	defer AfterEach(t)
+	cdpSession, err := page.Context().NewCDPSession(page)
+	if isChromium {
+		require.NoError(t, err)
+		_, err = cdpSession.Send("Console.enable", nil)
+		require.NoError(t, err)
+		cdpSession.On("Console.messageAdded", func(params map[string]interface{}) {
+			require.NotNil(t, params)
+		})
+		_, err = page.Evaluate(`console.log("hello")`)
+		require.NoError(t, err)
+		require.NoError(t, cdpSession.Detach())
+	} else {
+		require.Error(t, err)
+	}
+}
+
+func TestCDPSessionDetach(t *testing.T) {
+	BeforeEach(t)
+	defer AfterEach(t)
+	cdpSession, err := browser.NewBrowserCDPSession()
+	if isChromium {
+		require.NoError(t, err)
+		require.NoError(t, cdpSession.Detach())
+	} else {
+		require.Error(t, err)
+	}
+}