[Feature]: Add Gradle examples to documentation

[jhyot]

Feature request

Is it possible to add Gradle examples to the Playwright documentation along the current Maven ones?

[yury-s]

It'd be nice to have one! If anyone who uses Gradle is willing to contribute such an example we'd appreciate that.

[jhyot]

I am using gradle so I could try to reproduce all the examples, and then contribute them.

[jhyot]

It turns out that Gradle doesn't have a direct equivalent of Maven's exec:java goal. So the CLI commands cannot be translated 1:1 into Gradle. Instead, a new task or multiple tasks have to be defined in the project's build.gradle which then can be executed.

Because that requires a bit more description instead of just a "run this line" instruction, how would you like to integrate the gradle instructions into the doc?

Example of a task that needs to be added to build.gradle:

task runPlaywrightCli(type: JavaExec) {
  mainClass = 'com.microsoft.playwright.CLI'
  classpath sourceSets.main.runtimeClasspath
  args 'open'
}

Which can then be run with ./gradlew runPlaywrightCli

Also, gradle files can be written in Groovy (the original way) or in Kotlin (newer way which is pretty popular for new projects I think). How do you want to deal with this? I have only a Groovy setup, so couldn't easily test the Kotlin code.

[jhyot]

args above can also be set dynamically from the CLI, so the minimum would be to define one "generic" Playwright task, and then I think all the Maven examples can be translated into Gradle commands that run this task with a set of arguments.

[yury-s]

I thought you were originally talking about just gradle config for adding playwright deps but now I see that you are talking about all the cli examples. In that case I believe we'll need something like TypeScript/JavaScript tabs (see e.g. this page) but for the two build systems Maven/Gradle. As for the task definition I'd like the command line to be as close as possible to the node.js one. For example if it's

npx playwright open --device="iPhone 11" wikipedia.org

in nodejs it'd be nice to map it to something as concise as

./gradlew playwright open --device="iPhone 11" wikipedia.org

in a Gradle project. Would that be possible? As for the syntax preference we could provide the snippet in both Groovy and Kotlin similar to how Gradle docs do it. If not, I'd stay with more conservative option of Groovy as I'd expect clients that write their scripts in Kotlin to know how to translate Groovy to Kotlin.

You probably know this already but just in case, our docs live in the upstream repo and then we roll it periodically to playwright.dev to update it so these changes would need to go the playwright repo.

[andydelso]

Also, gradle files can be written in Groovy (the original way) or in Kotlin (newer way which is pretty popular for new projects I think). How do you want to deal with this? I have only a Groovy setup, so couldn't easily test the Kotlin code.

There are some neat setups on Gradle website that toggle between Groovy and Kotlin formats. Could that be implemented?

[andydelso]

It turns out that Gradle doesn't have a direct equivalent of Maven's exec:java goal. So the CLI commands cannot be translated 1:1 into Gradle. Instead, a new task or multiple tasks have to be defined in the project's build.gradle which then can be executed.

I think maybe you can get away with including the application plugin and setting the mainClass in the gradle(kotlin) build file:

plugins {
    application
    kotlin("jvm") version "1.5.0"
}

application {
    mainClass.set("com.microsoft.playwright.CLI")
}

...and then running this, but I could be wrong:

./gradlew run --args="install" // you can specify the browser here as well
./gradlew run --args="install-deps"

update:
Just tried both and then work along with browsing a page:
./gradlew run --args="open google.com"

[andydelso]

@jhyot and @yury-s - I think both an example gradle in both groovy and kotlin, along with these commands could be super useful in the docs! 😄

[yury-s]

There are some neat setups on Gradle website that toggle between Groovy and Kotlin formats. Could that be implemented?

Should be possible and I think this is the way to go.

I think maybe you can get away with including the application plugin and setting the mainClass in the gradle(kotlin) build file:

I like how concise the command line is in that case, but I'm concerned that it may get in conflict with the actual "application" in the project. Perhaps it's not an issue (I'm not familiar enough with Gradle)?

[andydelso]

@yury-s I am able to run tests locally using Playwright with a similar gradle setup. What would be the best way to test this?

[jhyot]

I like how concise the command line is in that case, but I'm concerned that it may get in conflict with the actual "application" in the project. Perhaps it's not an issue (I'm not familiar enough with Gradle)?

Yeah I would not use the application method as the main official way to use Playwright, because as you noted there can be only one application, and this might already be used by a project.

The best that I could come up with would be called something like this example command:

./gradlew playwright -Pargs="open --device='iPhone 11' wikipedia.org"

and this is the setup:

task playwright(type: JavaExec) {
  mainClass = 'com.microsoft.playwright.CLI'
  classpath sourceSets.main.runtimeClasspath
  if (project.hasProperty('args')) {
    args project.getProperty('args')
  }
}

[andydelso]

Yeah I would not use the application method as the main official way to use Playwright, because as you noted there can be only one application, and this might already be used by a project.

The application is actually the framework the user is wrapping around Playwright, and as I mentioned, this does not conflict. I was able to use exactly what I said locally in my own project. So I don't see the issue, but whatever is the best for the general user is going to be the right one, and that may not be mine 😆

[jhyot]

Yeah I would not use the application method as the main official way to use Playwright, because as you noted there can be only one application, and this might already be used by a project.

The application is actually the framework the user is wrapping around Playwright, and as I mentioned, this does not conflict. I was able to use exactly what I said locally in my own project. So I don't see the issue, but whatever is the best for the general user is going to be the right one, and that may not be mine 😆

Not sure if we are maybe misunderstanding each other. I thought (but haven't actually checked) that if a project already uses the application plugin for its own purpose, you can't add another application for playwright.

If your project doesn't use the application, then sure it will work.