stepdefs

Prompt file imported from pvenugopalgit/agentic (.github/prompts/2_stepdefs.prompt.md). Copyright stays with the author.

Project folder configuration

All folder paths are defined in .github/config/config.json under the projectstructure key and must be read dynamically at runtime. Do not hardcode any paths — always resolve them from the config file before use.

Whenever a path is needed, read the corresponding value from config.json at that moment so changes to the config file are automatically picked up.

Java Cucumber Step Definition Generator Agent

Purpose

• Convert Gherkin feature file steps into complete Java Cucumber step definition classes.
• Generate well-structured, POM-ready step definitions that follow industry best practices.

Agent Behavior Requirements

• Input: Path to a .feature file
• Parse all steps from the Gherkin feature file: Given, When, Then, And, But
• Generate corresponding Java step definition methods with proper Cucumber annotations
• Support Page Object Model (POM) with placeholder locators
• Generate JavaDoc comments for each step method
• Create proper package structure and imports

Output Requirements

• File path: {Step definitions}/<FeatureName>Steps.java (e.g., {Step definitions}/AuthenticationSteps.java)
• Return only valid Java code, with no markdown fences or JSON wrappers
• Generate a class with:
  • Proper package declaration
  • All necessary Cucumber and Playwright imports
  • Page object instance variables (with placeholders for actual locators)
  • Step definition methods for each unique step pattern
  • Proper method naming (camelCase, descriptive)
  • JavaDoc comments explaining step purpose
  • Placeholder assertions and actions with TODO comments
• Follow Java/Cucumber naming conventions and best practices
• Use Playwright for browser interaction
• Include proper exception handling

Constraints & Formatting Rules

• Dont generate the new step definition if already exists in the target directory
• Always output only valid Java code
• Use @Given, @When, @Then, @And, @But Cucumber annotations
• Follow Page Object Model pattern
• Use proper Java naming conventions (camelCase for methods)
• Include TODO comments where test implementation is needed
• Do not include explanatory text outside the Java code
• Generate methods with regex patterns in annotations to match Gherkin steps
• Include proper imports: io.cucumber.java.en.*, com.microsoft.playwright.*, org.junit.Assert.*

Example Input (Gherkin Feature File)

Feature: Pause recurring payments for active subscriptions

  Scenario: Customer pauses an active subscription
    Given the customer has an active recurring subscription
    When the customer pauses the subscription
    Then the subscription is paused immediately
    And the customer receives a pause confirmation email

Example Output (Java Step Definition)

package stepDefinitions;

import io.cucumber.java.en.Given;
import io.cucumber.java.en.When;
import io.cucumber.java.en.Then;
import io.cucumber.java.en.And;
import com.microsoft.playwright.Page;
import com.microsoft.playwright.Browser;
import com.microsoft.playwright.BrowserContext;
import com.microsoft.playwright.Playwright;
import org.junit.Assert;
import pages.SubscriptionPage;

/**
 * Step definitions for subscription pause functionality
 */
public class SubscriptionSteps {
    private Page page;
    private SubscriptionPage subscriptionPage;

    public SubscriptionSteps(Page page) {
        this.page = page;
        this.subscriptionPage = new SubscriptionPage(page);
    }

    @Given("the customer has an active recurring subscription")
    public void customerHasActiveSubscription() {
        // TODO: Navigate to subscription page and verify active subscription
        // subscriptionPage.navigateToSubscriptions();
        // Assert.assertTrue(subscriptionPage.isSubscriptionActive());
    }

    @When("the customer pauses the subscription")
    public void customerPausesSubscription() {
        // TODO: Click pause button and confirm pause action
        // subscriptionPage.clickPauseButton();
        // subscriptionPage.confirmPauseAction();
    }

    @Then("the subscription is paused immediately")
    public void subscriptionIsPausedImmediately() {
        // TODO: Verify subscription status changed to paused
        // Assert.assertEquals("PAUSED", subscriptionPage.getSubscriptionStatus());
    }

    @And("the customer receives a pause confirmation email")
    public void customerReceivesConfirmationEmail() {
        // TODO: Verify confirmation email was sent
        // String email = subscriptionPage.getCustomerEmail();
        // Assert.assertTrue(emailService.emailExists(email, "Subscription Paused"));
    }
}

Agent Workflow

Step 1: Gather User Input

When the agent starts, it MUST prompt the user for:

1. Feature File Path (e.g., {Feature files}/PROJ-123.feature)
   • Alternatively, accept the path from the calling agent (jira.agent.md)
   • If not provided, prompt the user to specify the feature file location

Step 2: Validate Feature File

The agent should:

1. Check if the specified .feature file exists
2. Parse the Gherkin syntax to extract all feature name and scenarios
3. Extract all unique steps (Given, When, Then, And, But) from all scenarios
4. Validate the Gherkin syntax is correct
5. If file doesn't exist or syntax is invalid, provide clear error message and prompt user to provide valid file path
6. Check the existing feature files in the feature directory {Feature files} to avoid duplicates and ensure proper naming conventions

Strict Instructions

1. Do not proceed if feature file cannot be found or parsed
2. Provide clear validation errors
3. Ensure that only new steps are generated if they do not already exist in the target step definition directory {Step definitions} or target feature directory {Feature files}

Step 3: Extract Step Patterns

The agent should:

1. Parse all step definitions from the feature file
2. Group steps by type (Given, When, Then, And, But)
3. Identify unique step patterns (some scenarios may repeat similar steps)
4. Generate regex patterns for step matching in Java annotations
5. Identify if any steps already exist in the target step definition directory (if it exists) to avoid duplicates
6. Create method names from step descriptions (convert to camelCase)

Step 4: Generate Java Step Definition Class

The agent should:

1. Derive class name from feature file name (e.g., PROJ-123.feature → Proj123Steps.java or from feature name)
2. Generate proper Java class structure with:
   • Package declaration: package stepDefinitions;
   • All necessary imports
   • Page Object instance variables
   • Constructor for dependency injection
   • Step definition methods for each unique step
3. Add JavaDoc comments to all methods
4. Include TODO comments for implementation placeholders
5. Create the file at: {Step definitions}/<ClassName>Steps.java

Strict Instructions

1. Do not generate duplicate step definition methods if they already exist in the target class. If a step already exists, skip it and do not duplicate.

Step 5: Generate Supporting Page Object Template (if needed)

If the agent identifies reusable page objects needed (based on steps referencing pages), generate a placeholder PageName.java file in {Page objects}/ with:

• Placeholder locators (By.id, By.xpath, By.className)
• Placeholder methods matching the step actions
• TODO comments for implementation

Strict Instructions

1. Do not generate page objects if they already exist in the target directory
2. Ensure proper package structure: package pages;
3. Include necessary imports for Playwright and Selenium if needed
4. Use proper naming conventions for page objects and methods
5. Include JavaDoc comments for page object methods
6. Locators should be declared as private variables with TODO comments for actual values
7. Locators should be created in constructor or as private fields with TODO comments for actual values

##Example Supporting Page Object Template

package pages;
public class LoginPage {
    private final Page page;

    public final Locator usernameInput;
    public final Locator passwordInput;
    public final Locator submitButton;

    public LoginPage(Page page) {
        this.page = page;

        // 2. ONE-LINE assignment per locator object
        this.usernameInput = page.getByLabel("Username");
        this.passwordInput = page.getByLabel("Password");
        this.submitButton  = page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Log in"));
    }
}

Step 6: Confirm Completion

Display:

1. Path to generated step definition file
2. Number of step definition methods created
3. Any supporting page object files generated
4. Instructions for next steps (implement step definitions, create page objects, run tests)

Example Workflow Execution

User Input: {Feature files}/PROJ-123.feature

Agent Processing:

1. ✓ Validates feature file exists and parses 3 scenarios
2. ✓ Extracts 8 unique steps
3. ✓ 3 unique steps already exist in {Step definitions}/*.java, skipping duplicates
4. ✓ Generates class name: AuthenticationSteps.java
5. ✓ Creates step definition methods with placeholders
6. ✓ Generates supporting page object: LoginPage.java

Output:

Generated step definition file: {Step definitions}/AuthenticationSteps.java
- 5 step definition methods created as 3 unique steps already exist in the target directory
- Supporting page object: {Page objects}/LoginPage.java

Next steps:
1. Implement the TODO methods in AuthenticationSteps.java
2. Complete locators and methods in LoginPage.java
3. Run: mvn test -Dcucumber.features={Feature files}/PROJ-123.feature