Runtime package for HTTP Forge generated Playwright API clients
npm install @http-forge/playwrightRuntime package for HTTP Forge generated Playwright API clients.
@http-forge/playwright provides lightweight runtime dependencies for TypeScript API clients generated by @http-forge/codegen. It includes environment variable management, URL building, and shared types to reduce code duplication in generated files.
``bash`
npm install @http-forge/playwright @playwright/test
- ForgeEnv: Environment and variable management for API clients
- Shared Types: Common types (headers, request context, options) to reduce generated code size
- Zero Dependencies: No runtime dependencies except peer dependency on @playwright/test
- Tree-shakeable: Multiple entry points for optimal bundle size
`typescript
import { ForgeEnv } from '@http-forge/playwright';
// Create environment with variables
const env = ForgeEnv.create({
baseUrl: 'https://api.example.com',
apiKey: 'your-api-key',
tenant: 'TELUS'
});
// Get variables
env.get('baseUrl'); // 'https://api.example.com'
// Resolve template strings
env.resolve('{{baseUrl}}/users'); // 'https://api.example.com/users'
// Build URLs with path params and query
env.buildUrl('{{baseUrl}}/users/:id', {
params: { id: '123' },
query: { include: 'profile' }
}); // 'https://api.example.com/users/123?include=profile'
`
`typescript
import { ForgeEnv } from '@http-forge/playwright';
const env = ForgeEnv.fromEnvironments(
{
dev: {
baseUrl: 'https://dev-api.example.com',
apiKey: 'dev-key'
},
sit: {
baseUrl: 'https://sit-api.example.com',
apiKey: 'sit-key'
},
prod: {
baseUrl: 'https://api.example.com',
apiKey: 'prod-key'
}
},
'dev' // active environment
);
// Switch environments
env.setActiveEnvironment('sit');
env.get('baseUrl'); // 'https://sit-api.example.com'
// List available environments
env.getEnvironments(); // ['dev', 'sit', 'prod']
`
`typescript
import { test } from '@playwright/test';
import { ForgeEnv } from '@http-forge/playwright';
import { loginRequest } from './api-clients/forgerock-login/login-request';
test('login with API client', async ({ request }) => {
const env = ForgeEnv.create({
baseUrl: 'https://auth.example.com',
clientId: 'my-client-id'
});
const response = await loginRequest({
request,
env,
query: {
client_id: '{{clientId}}',
response_type: 'code'
}
});
expect(response.ok()).toBeTruthy();
});
`
`typescript
import type { HttpHeaders, BaseRequestContext, BaseApiOptions } from '@http-forge/playwright/shared-types';
// Use HttpHeaders for type-safe header definitions
const headers: HttpHeaders = {
'Content-Type': 'application/json',
'Authorization': 'Bearer token',
'Custom-Header': 'value'
};
// Extend BaseRequestContext for custom request contexts
interface MyRequestContext extends BaseRequestContext {
customField?: string;
}
// Extend BaseApiOptions for custom options
interface MyOptions extends BaseApiOptions {
retries?: number;
}
`
#### Methods
- get(key: string): string | undefined - Get a variable value
- set(key: string, value: string): void - Set a variable value
- has(key: string): boolean - Check if variable exists
- delete(key: string): void - Delete a variable
- getAll(): Record
- resolve(template: string): string - Resolve {{variable}} placeholdersresolvePath(url: string, params?: Record
- - Resolve URL with path paramsbuildUrl(url: string, options?: { params?, query? }): string
- - Build complete URLresolveObject
- - Recursively resolve variables in an objectextractVariables(template: string): string[]
- - Extract variable names from templateextractPathParams(url: string): string[]
- - Extract path parameter names from URL
#### Environment Management
- getActiveEnvironment(): string | undefined - Get current environment name
- setActiveEnvironment(name: string): void - Switch to different environment
- getEnvironments(): string[] - List all available environments
- addEnvironment(name: string, vars: Record
#### Static Factory Methods
- ForgeEnv.create(variables: Record
- ForgeEnv.fromEnvironments(envs: Record
#### HttpHeaders
Interface for common HTTP headers with autocomplete support:
`typescript`
interface HttpHeaders {
'Content-Type'?: string;
'Authorization'?: string;
'Accept'?: string;
'Cache-Control'?: string;
// ... and more
[key: string]: any; // Allow custom headers
}
#### BaseRequestContext
Base interface for request context in generated clients:
`typescript`
interface BaseRequestContext {
request: APIRequestContext; // Playwright request context
env: IForgeEnv; // Environment instance
headers?: HttpHeaders; // Optional headers
}
#### BaseApiOptions
Common options for all API requests:
`typescript`
interface BaseApiOptions {
maxRedirects?: number; // Default: 20
timeout?: number; // Request timeout in ms
failOnStatusCode?: boolean; // Throw on non-2xx status
}
The package provides multiple entry points for tree-shaking:
`typescript
// Main entry - everything
import { ForgeEnv, type IForgeEnv, type HttpHeaders } from '@http-forge/playwright';
// Runtime only - ForgeEnv implementation
import { ForgeEnv, type IForgeEnv } from '@http-forge/playwright/forge-env';
// Types only - shared types
import type { HttpHeaders, BaseRequestContext, BaseApiOptions } from '@http-forge/playwright/shared-types';
`
When using @http-forge/codegen to generate API clients, they will automatically import from this package:
`typescript
// Generated file example
import type { IForgeEnv } from '@http-forge/playwright';
import type { HttpHeaders, BaseRequestContext, BaseApiOptions } from '@http-forge/playwright/shared-types';
import type { APIRequestContext, APIResponse } from '@playwright/test';
export interface LoginRequestOptions extends BaseRequestContext, BaseApiOptions {
query?: LoginRequestQuery;
}
export async function loginRequest(options: LoginRequestOptions): Promise
const { request, env } = options;
const url = env.buildUrl('https://auth.example.com/login', { query: options.query });
// ...
}
``
MIT