API Test Lib
npm install @liveauctioneers/api-test-libplaintext
- .env
- .env.example
- api.config.ts
- fixtures/
- package.json
- package-lock.json
- README.md
- resources/
- services/
- tests/
- utils/
`
Setup Instructions
1. Clone the Repository:
`bash
git clone git@github.com:globalauctionplatform/api-test-lib.git
`
2. Install Dependencies:
Navigate into the cloned directory and install required packages:
`bash
npm install
`
3. Configure Environment Variables:
- Copy the .env.example file to create a .env file:
`bash
cp .env.example .env
`
- Update the .env file with your actual environment variables (e.g., database credentials, service endpoints).
4. Run Tests:
Execute tests using the following command:
`bash
npm run test
`
Framework Architecture
$3
This structure organizes the framework into logical components:
1. The root directory handles configuration and project metadata.
2. fixtures/, resources/, and utils/: Provide reusable components like test data, payloads, utilities, and models.
3. services/: Encapsulates service-specific logic and endpoint definitions, as well as SQL query utility..
4. tests/: Contains test cases organized by feature or service.
`
fixtures/
fixtures.ts
resources/
addressPayload.json
services/
gap/
AuctionApprovalEndpoint.ts
GapService.ts
QueryHelper.ts
slb/
AuctionEndpoint.ts
SlbService.ts
timed_bidding/
TimedBiddingService.ts
tests/
api/
api.spec.ts
utils/
DateUtils.ts
DBConnector.ts
models/
AuctionApprovalData.ts
.env
.env.example
api.config.ts
package.json
package-lock.json
README.md
`
$3
- .env: Contains environment-specific variables, such as API keys, base URLs, and database credentials. This file should not be committed to version control.
- .env.example: A template for .env that lists all required environment variables without sensitive values.
- api.config.ts: Configuration file for the API testing framework. It may include setup details like base URLs, authentication tokens, and global configurations.
- package.json: Defines dependencies, scripts, and metadata for the project.
- package-lock.json: Locks the dependency tree to ensure consistent installations across environments.
- README.md: Documentation for the framework, including setup instructions, usage examples, and file structure.
$3
- fixtures.ts: Contains reusable test data or setup logic like service classes that can be injected into the test scenarios.
$3
Contains JSON files with payloads used in API requests, for instance:
- auctionPayload.json: Sample payload for auction-related operations.
$3
Contains service classes and endpoint definitions:
- gap/
- AuctionApprovalEndpoint.ts: Defines methods for interacting with the auction approval endpoint (e.g., approving auctions).
- BidderRegistrationEndpoint.ts: Contains methods for bidder registration operations.
- GapService.ts: Initializes the GAP service and provides access to its endpoints.
- QueryHelper.ts: A utility file that likely contains helper functions for querying data or performing common tasks across services.
- slb/
- AuctionEndpoint.ts: Contains methods for auction-related operations in SLB (e.g., creating auctions).
$3
Contains test cases organized by feature or service:
- api/
- api.spec.ts: Covers end-to-end scenarios for SBSv2
$3
Utility functions and helpers used across the framework:
- DateUtils.ts: Provides utility functions for handling dates and times (e.g., formatting, calculating durations).
- DBConnector.ts: Handles database connections and queries using MySQL2.
- models/:
- Contains TypeScript models representing data structures used in requests or responses:
- AuctionApprovalData.ts: Model for auction approval data.
$3
Services encapsulate configuration and expose endpoints. Example structure:
`typescript
class FooService {
private baseUrl: string;
private headers: Record;
private apiContext: APIRequestContext;
public auctionApprovalEndpoint: AuctionApprovalEndpoint;
public bidderRegistrationEndpoint: BidderRegistrationEndpoint;
constructor(baseUrl: string, apiKey: string) {
this.baseUrl = baseUrl;
this.headers = {
'Authorization': Bearer ${apiKey},
'Content-Type': 'application/json'
};
this.apiContext = await request.newContext({
baseURL: this.baseUrl,
extraHTTPHeaders: this.headers
});
this.auctionApprovalEndpoint = new AuctionApprovalEndpoint(this.apiContext);
this.bidderRegistrationEndpoint = new BidderRegistrationEndpoint(this.apiContext);
}
}
`
$3
Endpoint classes contain specific API operations:
`typescript
class AuctionApprovalEndpoint {
constructor(private apiContext: APIRequestContext) {}
async createCustomer(payload: CustomerPayload): Promise {
return this.apiContext.post('/v1/auctions/approvals', {
data: payload
});
}
}
`
$3
Tests are located in the tests/ directory. Services like gapService and slbService are initialized using Playwright fixtures, allowing you to use them directly in tests without manual setup.
$3
`typescript
test.only('Create auction Standard QA Environment', async ({ slbService, gapService }) => {
// Use services here
const createAuctionResponse = await slbService.auctionEndpoint.createAuction(AuctionCreationData.fromAuctionDuration(3, 'hour'));
const atgAuctionId = await createAuctionResponse.auctionDetails.atgAuctionId;
expect(atgAuctionId).toBeTruthy();
});
`
$3
1. Separation of Concerns:
- Services handle configuration
- Endpoints focus on specific API operations
2. Reusability: Endpoint methods can be reused across test scenarios
3. Type Safety: Strong typing for both payloads and responses
4. Centralized Configuration: Base URL and headers managed in one place
$3
1. Add a new service folder in services/, like foo/
2. Create the service class following the FooService pattern
3. Create corresponding endpoints in services/foo/
4. Add the corresponding service entry in the fixtures/fixtures.ts
5. Add the reference to the service Fixture in every scenario that needs it for test files in tests//
6. Enjoy!
$3
#### utils/DBConnector.ts
This module is responsible for configuring and managing the database connection. It provides a method to execute SQL queries:
- query(sql: string, params?: any[]): Executes a SQL query with optional parameters. This method is used throughout the framework to interact with the database.
#### utils/QueryHelper.ts
This utility class provides methods to query the database with retry logic for handling transient errors:
- retryOperation(operation: () => Promise): A private method that retries a given asynchronous operation up to MAX_RETRIES times with a delay of RETRY_DELAY_MS between attempts.
- getAuctionRecord(atgAuctionId: any): An example method that uses the retry logic to fetch an auction record from the database. This method is static and can be used across the framework.
#### Usage Example
`typescript
import { QueryHelper } from './utils/QueryHelper';
// Fetch an auction record with retry logic
const auctionRecord = await QueryHelper.getAuctionRecord('foo');
``