diff --git a/types/carlo/carlo-tests.ts b/types/carlo/carlo-tests.ts new file mode 100644 index 0000000000..d01636d969 --- /dev/null +++ b/types/carlo/carlo-tests.ts @@ -0,0 +1,32 @@ +import carlo = require('carlo'); + +async function main() { + const app = await carlo.launch({ + title: 'Test' + }); + + app.browserForTest(); + + const window = await app.createWindow({}); + window.setBounds({ + top: 10, + width: 30 + }); +} + +(async () => { + // Launch the browser. + const app = await carlo.launch(); + + // Terminate Node.js process on app window closing. + app.on('exit', () => process.exit()); + + // Tell carlo where your web files are located. + app.serveFolder(__dirname); + + // Expose 'env' function in the web environment. + await app.exposeFunction('env', _ => process.env); + + // Navigate to the main page of your app. + await app.load('example.html'); +})(); diff --git a/types/carlo/index.d.ts b/types/carlo/index.d.ts new file mode 100644 index 0000000000..7e7aea0fc3 --- /dev/null +++ b/types/carlo/index.d.ts @@ -0,0 +1,400 @@ +// Type definitions for carlo 0.9 +// Project: https://github.com/GoogleChromeLabs/carlo#readme +// Definitions by: Adam Dierkens +// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped +// TypeScript Version: 2.8 + +/// + +import { Serializable, Browser, Page } from "puppeteer-core"; + +export type Channel = string; + +/** + * Evaluates a function in the context of the page + * @param pageFunction Function to be evaluated in the page context. + * @param args Arguments to pass to pageFunction. + * + * If the function passed to the Window.evaluate returns a Promise, + * then Window.evaluate would wait for the promise to resolve and return its value. + * + * If the function passed to the Window.evaluate returns a non-Serializable value, + * then Window.evaluate resolves to undefined. + */ +export type EvaluateFunction = (pageFunction: ((...args: any[]) => any) | string, ...args: Serializable[]) => Promise; + +export interface WindowOptions { + /** + * App window width in pixels. + */ + width?: number; + + /** + * App window height in pixels. + */ + height?: number; + + /** + * App window top offset in pixels. + */ + top?: number; + + /** + * App window left offset in pixels. + */ + left?: number; + + /** + * Background color using hex notation, defaults to '#ffffff'. + */ + bgcolor?: string; +} + +/** + * Set of configurable options to set on the app. + */ +export interface LaunchOptions extends WindowOptions { + /** + * Browser to be used, defaults to ['stable'] + */ + channel?: Channel[]; + + /** + * Application icon to be used in the system dock. + * Either buffer containing PNG or a path to the PNG file on the file system. + * This feature is only available in Chrome M72+. + * One can use 'canary' channel to see it in action before M72 hits stable. + */ + icon?: Buffer | string; + + /** + * Optional parameters to share between Carlo instances. + */ + paramsForReuse?: any; + + /** + * Application title + */ + title?: string; + + /** + * Path to a User Data Directory. This folder is created upon the first app launch and contains user settings and Web storage data. Defaults to '.profile'. + */ + userDataDir?: string; + + /** + * Path to a Chromium or Chrome executable to run instead of the automatically located Chrome. + * If executablePath is a relative path, then it is resolved relative to current working directory. + * Carlo is only guaranteed to work with the latest Chrome stable version. + */ + executablePath?: string; + + /** + * Additional arguments to pass to the browser instance. + */ + args?: string[]; +} + +export type AppEvent = 'exit' | 'window'; +export type WindowEvent = 'close'; + +export interface Bounds { + /** + * Top offset in pixels. + */ + top: number; + + /** + * Left offset in pixels. + */ + left: number; + + /** + * Width in pixels. + */ + width: number; + + /** + * Height in pixels. + */ + height: number; +} + +export interface Window { + /** + * 'close' - Emitted when the window closes. + * @param name 'close' + */ + on(name: AppEvent, callback: (...args: any[]) => void): void; + + /** + * Returns window bounds + */ + bounds(): Promise; + + /** + * Brings this window to front. + */ + bringToFront(): Promise; + + /** + * Closes this window. + */ + close(): Promise; + + evaluate: EvaluateFunction; + + /** + * @param name Name of the function on the window object. + * @param carloFunction Callback function which will be called in Carlo's context. + */ + exposeFunction(name: string, carloFunction: (...args: any[]) => any): Promise; + + /** + * Turns the window into the full screen mode. Behavior is platform specific. + */ + fullscreen(): Promise; + + /** + * Navigates the corresponding web page to the given uri, + * makes given params available in web page via carlo.loadParams() + * Resolves upon DOMContentLoaded event in the web page. + * @param uri Path to the resource relative to the folder passed into serveFolder() + * @param params Optional parameters to pass to the web application. + */ + load(uri: string, params?: any): Promise; + + /** + * Maximizes the window. Behavior is platform-specific. + */ + maximize(): Promise; + + /** + * Minimizes the window. Behavior is platform-specific. + */ + minimize(): Promise; + + /** + * Returns Puppeteer page object for testing. + */ + pageForTest(): Page; + + /** + * Returns the options.paramsForReuse value passed into the carlo.launch. + */ + paramsForReuse(): any; + + /** + * Same as App.serveFolder(folder[, prefix]), but only applies to current window. + * @param folder Folder with web content to make available to Chrome. + * @param prefix Prefix of the URL path to serve from the given folder. + */ + serveFolder(folder: string, prefix?: string): void; + + /** + * Same as App.serveHandler(handler), but only applies to the current window requests. + * Only single window-level handler can be installed in window. + * @param handle Network handler callback accepting the HttpRequest parameter. + */ + serveHandler(handle: (request: HttpRequest) => void): void; + + /** + * Same as App.serveOrigin(base[, prefix]), but only applies to current window. + * @param base Base to serve web content from. + * @param prefix Prefix of the URL path to serve from the given folder. + */ + serveOrigin(base: string, prefix?: string): Promise; + + /** + * Sets window bounds. Parameters top, left, width and height are all optional. + * Dimension or the offset is only applied when specified. + * @param bounds Window bounds + */ + setBounds(bounds: { + /** + * Top offset in pixels. + */ + top?: number; + + /** + * Left offset in pixels. + */ + left?: number; + + /** + * Width in pixels. + */ + width?: number; + + /** + * Height in pixels. + */ + height?: number; + }): Promise; +} + +export interface HttpRequest { + /** + * Aborts request. + * If request is a navigation request, navigation is aborted as well. + */ + abort(): Promise; + + /** + * Proceeds with the default behavior for this request. + * Either serves it from the filesystem or defers to the browser. + */ + continue(): Promise; + + /** + * Marks the request as failed. + * If request is a navigation request, navigation is still committed, but to a location that fails to be fetched. + */ + fail(): Promise; + + /** + * Fulfills the network request with the given data. 'Content-Length' header is generated in case it is not listed in the headers. + */ + fulfill(options: { + /** + * HTTP status code (200, 304, etc), defaults to 200. + */ + status: number; + + /** + * HTTP response headers. + */ + headers: object; + + /** + * Response body. + */ + body: Buffer; + }): Promise; + + /** + * Network request headers + */ + headers(): object; + + /** + * HTTP method of this network request (GET, POST, etc.) + */ + method(): string; + + /** + * Network request URL + */ + url(): string; +} + +export interface App { + /** + * 'exit' - Emitted when the last window closes. + * 'window' - Emitted when the new window opens. + * @param name 'exit' or 'window' + * @param callback + */ + on(name: AppEvent, callback: (...args: any[]) => void): void; + + /** + * Puppeteer browser object for testing. + */ + browserForTest(): Browser; + + createWindow(options?: WindowOptions): Promise; + + evaluate: EvaluateFunction; + + /** + * Closes the browser window + */ + exit(): Promise; + + /** + * The method adds a function called name on the pages' window object. + * When called, the function executes carloFunction in Node.js and returns a Promise which resolves to the return value of carloFunction. + * @param name + * @param carloFunction + */ + exposeFunction(name: string, carloFunction: (...args: any[]) => any): Promise; + + /** + * Shortcut to the main window's Window.load + * @param uri + * @param params + */ + load(uri: string, ...params: any[]): Promise; + + /** + * Running app guarantees to have main window. + * If current main window closes, a next open window becomes the main one. + */ + mainWindow(): Window; + + /** + * Makes the content of the given folder available to the Chrome web app + * @param folder Folder with web content to make available to Chrome + * @param prefix Prefix of the URL path to serve from the given folder + */ + serveFolder(folder: string, prefix?: string): void; + + /** + * Handler function is called with every network request in this app. + * It can abort, continue or fulfill each request. + * Only single app-wide handler can be registered. + * @param handler Network handler callback accepting the HttpRequest parameter. + */ + serveHandler(handler: (request: HttpRequest) => void): void; + + /** + * Fetches Carlo content from the specified origin instead of reading it from the file system, eg http://localhost:8080. + * This mode can be used for the fast development mode available in web frameworks. + * @param base Base to serve web content from. + * @param prefix Prefix of the URL path to serve from the given folder. + */ + serveOrigin(base: string, prefix?: string): void; + + /** + * Specifies image to be used as an app icon in the system dock. + * This feature is only available in Chrome M72+. One can use 'canary' channel to see it in action before M72 hits stable. + * @param image Either buffer containing PNG or a path to the PNG file on the file system. + */ + setIcon(image: Buffer | string): void; + + /** + * Returns all currently opened windows. + * Running app guarantees to have at least one open window. + */ + windows(): Window[]; +} + +/** + * Launches the browser + * @param options Set of configurable options to set on the app. + */ +export function launch(options?: LaunchOptions): Promise; + +/** + * Enters headless test mode. + */ +export function enterTestMode(): void; + +/** + * Returns additional information about the file, otherwise not available to the web. + * Available in Chrome M73+ + * + * @param file File to get additional information for + */ +export function fileInfo(file: any): Promise<{ + /** + * absolute path to the given file + */ + path: string; +}>; + +/** + * This method is available in the Web world and returns parameters passed into the window.load(). + * This is how Carlo passes initial set of handles to Node objects into the web world. + */ +export function loadParams(): Promise>; diff --git a/types/carlo/tsconfig.json b/types/carlo/tsconfig.json new file mode 100644 index 0000000000..6bb4f11fe4 --- /dev/null +++ b/types/carlo/tsconfig.json @@ -0,0 +1,25 @@ +{ + "compilerOptions": { + "module": "commonjs", + "lib": [ + "es6", + "dom" + ], + "target": "es2017", + "noImplicitAny": true, + "noImplicitThis": true, + "strictNullChecks": true, + "strictFunctionTypes": true, + "baseUrl": "../", + "typeRoots": [ + "../" + ], + "types": [], + "noEmit": true, + "forceConsistentCasingInFileNames": true + }, + "files": [ + "index.d.ts", + "carlo-tests.ts" + ] +} \ No newline at end of file diff --git a/types/carlo/tslint.json b/types/carlo/tslint.json new file mode 100644 index 0000000000..3db14f85ea --- /dev/null +++ b/types/carlo/tslint.json @@ -0,0 +1 @@ +{ "extends": "dtslint/dt.json" }