aom

API Object Model Standards

Structure

• Use @Fixture decorator with PascalCase name matching class name (e.g., @Fixture('PostsService'))
• Export class with descriptive name ending in Service (e.g., PostsService, AuthService)
• Constructor receives APIRequestContext as private request: APIRequestContext or protected request: APIRequestContext
• Organize services into services/ directory within each challenge
• Define TypeScript interfaces for request/response types at the top of the file
• Define endpoint constants as private readonly properties or private methods

Step Definitions

• Use @Given, @When, @Then decorators from @world for step definitions that match Gherkin scenarios
• Step text must match Gherkin scenarios exactly
• All step methods must be async
• Step methods receive parameters from Gherkin (e.g., {string}, {int})
• Always call setLastResponse(response) after API calls to enable shared step definitions
• Use ResponseVerifier utilities for common response checks

Internal Helper Methods

• Use @Step decorator for internal helper methods that should appear in Playwright test reports
• All methods with @Step decorator must start with "i" following BDD naming convention:
  • iVerify... for verification checks
  • iValidate... for validation checks
  • iCheck... for assertion checks
• Examples: iVerifyResponseIsOk(), iVerifyPostStructure(), iValidateUserData()
• Use Playwright's expect for all assertions

Response Handling

• Store last response in private property: private lastResponse: Awaited<ReturnType<...>> | null = null
• Store parsed response data in typed properties (e.g., private lastPost: Post | null = null)
• Always call setLastResponse(response) after API calls to enable shared verification steps
• Use getLastResponse() from response-tracker utility when needed in shared steps
• Parse JSON responses immediately after status verification

Error Handling

• Always verify response status codes using ResponseVerifier.verifyResponseStatus()
• Check response.ok() for 2xx status codes before parsing JSON
• Handle error responses separately (store in lastErrorResponse property)
• Throw descriptive errors when required data is missing (e.g., "No response available. Perform an API request first.")