diff --git a/README.md b/README.md index 6a163d6..d96ef65 100644 --- a/README.md +++ b/README.md @@ -39,48 +39,116 @@ More info about https://jitpack.io/ ## Usage -* Create config +### Configuration +In order to initialize VisualRegressionTracker, following options should be defined: + +* `apiUrl` (**Required**) - URL where backend is running. _Example_: "http://localhost:4200" +* `project` (**Required**) - Project name or ID. _Example_: "003f5fcf-6c5f-4f1f-a99f-82a697711382" +* `apiKey` (**Required**) - User apiKey. _Example_: "F5Z2H0H2SNMXZVHX0EA4YQM1MGDD" +* `branch` (Optional) - Current git branch. _Example_: "develop" +* `enableSoftAssert` (Optional) - Log errors instead of exceptions. Default value is false +* `ciBuildId` (Optional) - id of the build in CI system +* `httpTimeoutInSeconds` (Optional) - define http socket timeout in seconds. Default value is 10 seconds + + There are a few ways to provide those options + +
+ +Create config with builder ```java -VisualRegressionTrackerConfig config = new VisualRegressionTrackerConfig( - // apiUrl - URL where backend is running - "http://localhost:4200", - - // project - Project name or ID - "003f5fcf-6c5f-4f1f-a99f-82a697711382", - - // apiKey - User apiKey - "F5Z2H0H2SNMXZVHX0EA4YQM1MGDD", - - // branch - Current git branch - "develop", - - // enableSoftAssert - Log errors instead of exceptions - false, - - // ciBuildId - id of the build in CI system - "CI_BUILD_ID", - - // httpTimeoutInSeconds - define http socket timeout in seconds (default 10s) - 15 +VisualRegressionTrackerConfig config = VisualRegressionTrackerConfig.builder() + .apiUrl("http://localhost:4200") + .apiKey("F5Z2H0H2SNMXZVHX0EA4YQM1MGDD") + .project("003f5fcf-6c5f-4f1f-a99f-82a697711382") + .enableSoftAssert(true) + .branchName("develop") + .build(); +``` + +
+ +
+ +Set environment variables + +``` +export VRT_APIURL=http://localhost:4200 +export VRT_APIKEY=F5Z2H0H2SNMXZVHX0EA4YQM1MGDD +export VRT_PROJECT=003f5fcf-6c5f-4f1f-a99f-82a697711382 +export VRT_BRANCHNAME=develop +export VRT_ENABLESOFTASSERT=true +export VRT_CIBUILDID=40bdba4 +export VRT_HTTPTIMEOUTINSECONDS=15 -); ``` -* Create an instance of `VisualRegressionTracker` +
+ +
+ +Create vrt.json file in the root of the project + +```json +{ + "apiUrl": "[http://162.243.161.172:4200](http://localhost:4200)", + "project": "003f5fcf-6c5f-4f1f-a99f-82a697711382", + "apiKey": "F5Z2H0H2SNMXZVHX0EA4YQM1MGDD", + "branchName": "develop", + "enableSoftAssert": false, + "ciBuildId": "40bdba4" +} + +``` + +
+ +> [!NOTE] +> Final values, that will be used by VisualRegressionTracker, will be resolved as following: +> 1. If explicitly set while creating `VisualRegressionTrackerConfig` - use this value +> 2. Use value from environment variable if it exists +> 3. Try to get it from the configuration file + +
+ + +### Create an instance of `VisualRegressionTracker` ```java VisualRegressionTracker visualRegressionTracker = new VisualRegressionTracker(config); ``` -* Take a screenshot as String in Base64 format +or + +```java +VisualRegressionTracker visualRegressionTracker = new VisualRegressionTracker(); +``` + +> [!TIP] +> If config is not provided explicitly, it will be created based on the environment variables or configuration file. Please see [Configuration](README.md#configuration) section + +
+ +### Start `VisualRegressionTracker` + +```java +visualRegressionTracker.start(); +``` + +At that point VisualRegressionTracker will try to create a new build for provided project. All of the subsequent tracked screenshots are going to be included in that build. + +
+ +### Take a screenshot as String in Base64 format ```java // Selenium example String screenshotBase64 = ((TakesScreenshot) driver).getScreenshotAs(OutputType.BASE64); ``` -* Track image +
+ +### Track image Default options @@ -105,3 +173,12 @@ visualRegressionTracker.track( .build() ); ``` + + +### Stop `VisualRegressionTracker` + +```java +visualRegressionTracker.stop(); +``` + +Should be called once current build should be considered as completed.