Skip to content

Commit 67db041

Browse files
stracker-philstracker-phil
authored
Merge pull request #2 from mirao/Create_TypeScript_Definition
Created a TypeScript definition
2 parents d4bc14a + 15c2810 commit 67db041

File tree

2 files changed

+357
-4
lines changed

2 files changed

+357
-4
lines changed

‎index.d.ts

+353
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,353 @@
1+
export = PixelmatchHelper;
2+
/**
3+
* Helper class that integrates pixelmatch into CodeceptJS for visual regression
4+
* tests.
5+
*
6+
* helpers: {
7+
* PixelmatchHelper: {
8+
* require: "codeceptjs-pixelmatchhelper",
9+
* dirExpected: "./tests/screenshots/base/",
10+
* dirDiff: "./tests/screenshots/diff/",
11+
* dirActual: "./tests/output/", // Optional. Defaults to global.output_dir.
12+
* diffPrefix: "Diff_" // Optional. Defaults to "Diff_"
13+
* tolerance: 1.5,
14+
* threshold: 0.1,
15+
* dumpIntermediateImage: false,
16+
* captureActual: true,
17+
* captureExpected: true
18+
* }
19+
* }
20+
*
21+
* @author Philipp Stracker
22+
*/
23+
declare class PixelmatchHelper {
24+
/**
25+
* Constructor that initializes the helper.
26+
* Called internally by CodeceptJS.
27+
*
28+
* @param {object} config
29+
*/
30+
constructor(config: object);
31+
/**
32+
* Relative path to the folder that contains relevant images.
33+
*
34+
* @type {{expected: string, actual: string, diff: string}}
35+
*/
36+
globalDir: {
37+
expected: string;
38+
actual: string;
39+
diff: string;
40+
};
41+
/**
42+
* Default tolserance level for comparisons.
43+
*
44+
* @type {float}
45+
*/
46+
globalTolerance: float;
47+
/**
48+
* Default threshold for all comparisons.
49+
*
50+
* @type {float}
51+
*/
52+
globalThreshold: float;
53+
/**
54+
* Filename prefix for generated difference files.
55+
* @type {string}
56+
*/
57+
globalDiffPrefix: string;
58+
/**
59+
* Whether to save the intermediate images to the global output folder,
60+
* after applying the bounds and ignore-boxes.
61+
*
62+
* Useful for debugging tests, but not recommended for production usage.
63+
*
64+
* @type {boolean}
65+
*/
66+
globalDumpIntermediateImage: boolean;
67+
/**
68+
* Whether to capture a new screenshot and use it as actual image, instead
69+
* of loading the image from the `dirActual` folder.
70+
*
71+
* The new screenshot is saved to the `dirActual` folder before comparison,
72+
* and will replace an existing file with the same name!
73+
*
74+
* @type {boolean|'missing'}
75+
*/
76+
globalCaptureActual: boolean | 'missing';
77+
/**
78+
* Whether to update the expected base image with a current screenshot
79+
* before starting the comparison.
80+
*
81+
* The new screenshot is saved to the `dirExpected` folder, and will
82+
* replace an existing file with the same name!
83+
*
84+
* @type {boolean|'missing'}
85+
*/
86+
globalCaptureExpected: boolean | 'missing';
87+
/**
88+
* Contains the image paths for the current test.
89+
*
90+
* @type {{expected: string, actual: string, diff: string}}
91+
*/
92+
path: {
93+
expected: string;
94+
actual: string;
95+
diff: string;
96+
};
97+
/**
98+
* Comparison options.
99+
*
100+
* @type {object}
101+
*/
102+
options: object;
103+
/**
104+
* Name of the image to compare.
105+
*
106+
* @type {string}
107+
*/
108+
imageName: string;
109+
/**
110+
* Holds comparison results.
111+
*
112+
* @type {{match: boolean, difference: float, diffImage: string, diffPixels: integer,
113+
* totalPixels: integer, relevantPixels: integer}}
114+
*/
115+
result: {
116+
match: boolean;
117+
difference: float;
118+
diffImage: string;
119+
diffPixels: integer;
120+
totalPixels: integer;
121+
relevantPixels: integer;
122+
};
123+
/**
124+
* Compares the given screenshot with the expected image. When too many
125+
* differences are detected, the test will fail.
126+
*
127+
* I.checkVisualDifferences('dashboard.png');
128+
* I.checkVisualDifferences('dashboard.png', { screenshot: true });
129+
*
130+
* @param {string} image - Name of the input image to compare.
131+
* @param {object} [options] - Optional options for the comparison.
132+
* @return {Promise}
133+
*/
134+
checkVisualDifferences(image: string, options?: object): Promise<any>;
135+
/**
136+
* Compares the given screenshot with the expected image and updates the
137+
* class member `this.result` with details. This function does to trigger an
138+
* assertion but can throw an error, when the images cannot be compared.
139+
*
140+
* @param {string} image - Name of the input image to compare.
141+
* @param {object} [options] - Optional options for the comparison.
142+
* @return {{match: boolean, difference: float}} Comparison details.
143+
*/
144+
getVisualDifferences(image: string, options?: object): {
145+
match: boolean;
146+
difference: float;
147+
};
148+
/**
149+
* Take screenshot of individual element.
150+
*
151+
* @param {string} name - Name of the output image.
152+
* @param {'actual'|'expected'} [which] - Optional. Whether the screenshot is
153+
* the expected bas eimage, or an actual image for comparison.
154+
* Defaults to 'actual'.
155+
* @param {string} [element] - Optional. Selector of the element to
156+
* screenshot, or empty to screenshot current viewport.
157+
* @returns {Promise}
158+
*/
159+
takeScreenshot(name: string, which?: 'actual' | 'expected', element?: string): Promise<any>;
160+
/**
161+
* Takes a screenshot of the entire viewport and saves it as either an
162+
* actual image, or an expected base-image.
163+
*
164+
* @param {string} name - Name of the output image.
165+
* @param {'actual'|'expected'} which - Optional. Whether the screenshot is
166+
* the expected bas eimage, or an actual image for comparison.
167+
* Defaults to 'actual'.
168+
* @param {string} element - Optional. Selector of the element to
169+
* screenshot, or empty to screenshot current viewport.
170+
* @private
171+
*/
172+
private _takeElementScreenshot;
173+
/**
174+
* Takes a screenshot of the entire viewport and saves it as either an
175+
* actual image, or an expected base-image.
176+
*
177+
* @param {string} name - Name of the output image.
178+
* @param {'actual'|'expected'} which - Optional. Whether the screenshot is
179+
* the expected bas eimage, or an actual image for comparison.
180+
* Defaults to 'actual'.
181+
* @private
182+
*/
183+
private _takeScreenshot;
184+
/**
185+
* Clears pixels in the specified image that are outside the bounding rect
186+
* or inside an ignored area.
187+
*
188+
* @param {PNG} png - The image to modify.
189+
* @return {int} Number of cleared pixels.
190+
* @private
191+
*/
192+
private _applyBounds;
193+
/**
194+
* Determines the bounding box of the given element on the current viewport.
195+
*
196+
* @param {string} selector - CSS|XPath|ID selector.
197+
* @returns {Promise<{boundingBox: {left: int, top: int, right: int, bottom: int, width: int,
198+
* height: int}}>}
199+
*/
200+
_getBoundingBox(selector: string): Promise<{
201+
boundingBox: {
202+
left: int;
203+
top: int;
204+
right: int;
205+
bottom: int;
206+
width: int;
207+
height: int;
208+
};
209+
}>;
210+
/**
211+
* Captures the expected or actual image, depending on the captureFlag.
212+
*
213+
* @param {string} which - Which image to capture: 'expected', 'actual'.
214+
* @param {bool|string} captureFlag - Either true, false or 'missing'.
215+
* @private
216+
*/
217+
private _maybeCaptureImage;
218+
/**
219+
* Sanitizes the given options and updates all relevant class members with
220+
* either the new, sanitized value, or with a default value.
221+
*
222+
* @param {string} image - Name of the image to compare.
223+
* @param {object|undefined} options - The new options to set.
224+
* @private
225+
*/
226+
private _setupTest;
227+
/**
228+
* Returns the instance of the current browser driver.
229+
*
230+
* @return {Puppeteer|WebDriver|Appium|WebDriverIO|TestCafe}
231+
* @private
232+
*/
233+
private _getDriver;
234+
/**
235+
* Recursively creates the specified directory.
236+
*
237+
* @param dir
238+
* @private
239+
*/
240+
private _mkdirp;
241+
/**
242+
* Deletes the specified file, if it exists.
243+
*
244+
* @param {string} file - The file to delete.
245+
* @private
246+
*/
247+
private _deleteFile;
248+
/**
249+
* Tests, if the given file exists..
250+
*
251+
* @param {string} file - The file to check.
252+
* @param {string} mode - Optional. Either empty, or 'read'/'write' to
253+
* validate that the current user can either read or write the file.
254+
* @private
255+
*/
256+
private _isFile;
257+
/**
258+
* Builds the absolute path to a relative folder.
259+
*
260+
* @param {string} dir - The relative folder name.
261+
* @returns {string}
262+
* @private
263+
*/
264+
private _resolvePath;
265+
/**
266+
* Returns the filename of an image.
267+
*
268+
* @param {string} which - Which image to return (expected, actual, diff).
269+
* @param {string} suffix - Optional. A suffix to append to the filename.
270+
* @private
271+
*/
272+
private _getFileName;
273+
/**
274+
* Builds an image path using the current image name and the specified folder.
275+
*
276+
* @param {string} which - The image to load (expected, actual, diff).
277+
* @param {string} suffix - Optional. A suffix to append to the filename.
278+
* @returns {string} Path to the image.
279+
* @private
280+
*/
281+
private _buildPath;
282+
/**
283+
* Returns a list of absolute image paths of base images for the comparison.
284+
* All files in the returned list exist in the filesystem.
285+
*
286+
* Naming convention:
287+
*
288+
* Files that contain a trailing "~<num>" suffix are considered part of the
289+
* matching list.
290+
*
291+
* For example:
292+
*
293+
* image: "google-home"
294+
* files:
295+
* "google-home.png" # exact match
296+
* "google-home~1.png" # variation
297+
* "google-home~83.png" # variation
298+
*
299+
* @return {string[]}
300+
* @private
301+
*/
302+
private _getExpectedImagePaths;
303+
/**
304+
* Loads the specified image and returns a PNG blob.
305+
*
306+
* @param {string} which - The image to load (expected, actual, diff).
307+
* @param {string} suffix - Optional. A suffix to append to the filename.
308+
* @return {object} An PNG object.
309+
* @private
310+
*/
311+
private _loadPngImage;
312+
/**
313+
* Saves the specified PNG image to the filesystem.
314+
* .
315+
* @param {string} which - The image to load (expected, actual, diff).
316+
* @param {object} png - An PNG image object.
317+
* @param {string} suffix - Optional. A suffix to append to the filename.
318+
* @private
319+
*/
320+
private _savePngImage;
321+
/**
322+
* Clears a rectangular area inside the given PNG image object. The change
323+
* is only applied in-memory and does not affect the saved image.
324+
*
325+
* @param {object} png - The PNG object.
326+
* @param {int} x0
327+
* @param {int} y0
328+
* @param {int} x1
329+
* @param {int} y1
330+
* @return {int} Number of cleared pixels.
331+
* @private
332+
*/
333+
private _clearRect;
334+
/**
335+
* Casts the given value into a boolean. Several string terms are translated
336+
* to boolean true. If validTerms are specified, and the given value matches
337+
* one of those validTerms, the term is returned instead of a boolean.
338+
*
339+
* Sample:
340+
*
341+
* _toBool('yes') --> true
342+
* _toBool('n') --> false
343+
* _toBool('any') --> false
344+
* _toBool('ANY', ['any', 'all']) --> 'any'
345+
*
346+
* @param {any} value - The value to cast.
347+
* @param {array} validTerms - List of terms that should not be cast to a
348+
* boolean but returned directly.
349+
* @return {bool|string} Either a boolean or a lowercase string.
350+
* @private
351+
*/
352+
private _toBool;
353+
}

‎index.js

+4-4
Original file line numberDiff line numberDiff line change
@@ -232,7 +232,7 @@ class PixelmatchHelper extends Helper {
232232
* I.checkVisualDifferences('dashboard.png', { screenshot: true });
233233
*
234234
* @param {string} image - Name of the input image to compare.
235-
* @param {object} options - Optional options for the comparison.
235+
* @param {object} [options] - Optional options for the comparison.
236236
* @return {Promise}
237237
*/
238238
checkVisualDifferences(image, options) {
@@ -267,7 +267,7 @@ class PixelmatchHelper extends Helper {
267267
* assertion but can throw an error, when the images cannot be compared.
268268
*
269269
* @param {string} image - Name of the input image to compare.
270-
* @param {object} options - Optional options for the comparison.
270+
* @param {object} [options] - Optional options for the comparison.
271271
* @return {{match: boolean, difference: float}} Comparison details.
272272
*/
273273
async getVisualDifferences(image, options) {
@@ -384,10 +384,10 @@ class PixelmatchHelper extends Helper {
384384
* Take screenshot of individual element.
385385
*
386386
* @param {string} name - Name of the output image.
387-
* @param {'actual'|'expected'} which - Optional. Whether the screenshot is
387+
* @param {'actual'|'expected'} [which] - Optional. Whether the screenshot is
388388
* the expected bas eimage, or an actual image for comparison.
389389
* Defaults to 'actual'.
390-
* @param {string} element - Optional. Selector of the element to
390+
* @param {string} [element] - Optional. Selector of the element to
391391
* screenshot, or empty to screenshot current viewport.
392392
* @returns {Promise}
393393
*/

0 commit comments

Comments
 (0)