{"id":19380348,"url":"https://github.com/atata-framework/atata-htmlvalidation","last_synced_at":"2025-04-23T19:33:35.706Z","repository":{"id":47963575,"uuid":"379868682","full_name":"atata-framework/atata-htmlvalidation","owner":"atata-framework","description":".NET library that adds HTML page validation to Atata using html-validate NPM package","archived":false,"fork":false,"pushed_at":"2024-08-07T15:34:06.000Z","size":153,"stargazers_count":4,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-10-29T12:33:22.649Z","etag":null,"topics":["atata","csharp","dotnet","framework","html","html-validate","html-validation","test-automation","testing","validation"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/atata-framework.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"open_collective":"atata"}},"created_at":"2021-06-24T09:16:17.000Z","updated_at":"2024-08-07T15:34:10.000Z","dependencies_parsed_at":"2024-01-18T11:05:26.654Z","dependency_job_id":"ad7f487b-58aa-46dc-b2ea-9195c5b658c6","html_url":"https://github.com/atata-framework/atata-htmlvalidation","commit_stats":{"total_commits":130,"total_committers":1,"mean_commits":130.0,"dds":0.0,"last_synced_commit":"a8a02419b76c8c9b751c876177e1e2a4a99a144d"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":"atata-framework/atata-repository-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atata-framework%2Fatata-htmlvalidation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atata-framework%2Fatata-htmlvalidation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atata-framework%2Fatata-htmlvalidation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atata-framework%2Fatata-htmlvalidation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/atata-framework","download_url":"https://codeload.github.com/atata-framework/atata-htmlvalidation/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223780048,"owners_count":17201280,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["atata","csharp","dotnet","framework","html","html-validate","html-validation","test-automation","testing","validation"],"created_at":"2024-11-10T09:13:41.820Z","updated_at":"2025-04-23T19:33:35.698Z","avatar_url":"https://github.com/atata-framework.png","language":"C#","funding_links":["https://opencollective.com/atata"],"categories":[],"sub_categories":[],"readme":"# Atata.HtmlValidation\n\n[![NuGet](http://img.shields.io/nuget/v/Atata.HtmlValidation.svg?style=flat)](https://www.nuget.org/packages/Atata.HtmlValidation/)\n[![GitHub release](https://img.shields.io/github/release/atata-framework/atata-htmlvalidation.svg)](https://github.com/atata-framework/atata-htmlvalidation/releases)\n[![Build status](https://dev.azure.com/atata-framework/atata-htmlvalidation/_apis/build/status/atata-htmlvalidation-ci?branchName=main)](https://dev.azure.com/atata-framework/atata-htmlvalidation/_build/latest?definitionId=47\u0026branchName=main)\n[![Slack](https://img.shields.io/badge/join-Slack-green.svg?colorB=4EB898)](https://join.slack.com/t/atata-framework/shared_invite/zt-5j3lyln7-WD1ZtMDzXBhPm0yXLDBzbA)\n[![Atata docs](https://img.shields.io/badge/docs-Atata_Framework-orange.svg)](https://atata.io)\n[![Twitter](https://img.shields.io/badge/follow-@AtataFramework-blue.svg)](https://twitter.com/AtataFramework)\n\n**Atata.HtmlValidation** is a .NET library that adds HTML page validation to [Atata](https://github.com/atata-framework/atata) using [html-validate](https://www.npmjs.com/package/html-validate) NPM package.\n\n*The package targets .NET Standard 2.0, which supports .NET 5+, .NET Framework 4.6.1+ and .NET Core/Standard 2.0+.*\n\n## Table of Contents\n\n- [Features](#features)\n- [Installation](#installation)\n- [Usage](#usage)\n  - [Using `ValidateHtml` extension method](#using-validatehtml-extension-method) \n  - [Using `ValidateHtmlAttribute` trigger](#using-validatehtmlattribute-trigger)\n  - [Using `HtmlValidator`](#using-htmlvalidator)\n- [Configuration](#configuration)\n- [`HtmlValidationOptions` properties](#htmlvalidationoptions-properties)\n- [`HtmlValidationResult` members](#htmlvalidationresult-members)\n- [Validation results](#validation-results)\n  - [Exception](#exception)\n  - [Result file](#result-file)\n  - [Log](#log)\n- [Sample project](#sample-project)\n- [Feedback](#feedback)\n- [Thanks](#thanks)\n- [SemVer](#semver)\n- [License](#license)\n\n## Features\n\n- Uses [CLI of html-validate](https://html-validate.org/usage/cli.html) NPM package.\n- Validates HTML of Atata page objects.\n- Performs validation offline.\n- Supports different result formatters.\n- Supports custom validation rule sets by configuration files.\n- Saves HTML and validation results to artifact files.\n- Can produce either error or warning.\n\n## Installation\n\n### NuGet package\n\nInstall [`Atata.HtmlValidation`](https://www.nuget.org/packages/Atata.HtmlValidation/) NuGet package.\n\n- Package Manager:\n  ```\n  Install-Package Atata.HtmlValidation\n  ```\n\n- .NET CLI:\n  ```\n  dotnet add package Atata.HtmlValidation\n  ```\n\n### NPM package\n\nRequires [html-validate](https://www.npmjs.com/package/html-validate) NPM package,\nas well as NPM itself, to be installed.\nBy default, when `html-validate` package is missing,\nthe library automatically tries to install the package,\nbut in case of permissions lack, installation can fail.\nTherefore, it is recommended when possible to preinstall `html-validate` package using NPM command:\n\n```\nnpm install -g html-validate\n```\n\n## Usage\n\n### Using `ValidateHtml` extension method\n\nThe primary way to execute validations is using `ValidateHtml` extension method:\n\n```cs\npublic static TPageObject ValidateHtml\u003cTPageObject\u003e(\n    this TPageObject pageObject,\n    HtmlValidationOptions options = null,\n    bool asWarning = false)\n    where TPageObject : PageObject\u003cTPageObject\u003e;\n```\n\nThe method validates the HTML of current page.\nRelies on `HtmlValidator` class\nthat uses \"html-validate\" NPM package to execute HTML validation.\n\nBefore the execution of validation, the check of installed \"html-validate\" package version performs.\nThe required package version is defined in `HtmlValidatePackageVersion` property of `options`.\nThe required version will be installed if \"html-validate\" package is not installed or the installed version differs from the required one.\n\nBy default, when validation fails, throws an assertion exception with a message containing a list of HTML errors.\nProduces a warning instead of assertion exception if `asWarning` argument is set to `true`.\n\n#### Validate by default\n\n```cs\nGo.To\u003cOrdinaryPage\u003e(url: \"some/url\")\n    .ValidateHtml();\n```\n\n#### Validate as warning\n\n```cs\nGo.To\u003cOrdinaryPage\u003e(url: \"some/url\")\n    .ValidateHtml(asWarning: true);\n```\n\n#### Validate with custom options\n\n```cs\nvar options = new HtmlValidationOptions\n{\n    OutputFormatter = HtmlValidateFormatter.Names.Text,\n    ResultFileFormatter = HtmlValidateFormatter.Names.Json,\n    ConfigPath = \"some/config.json\"\n};\n\nGo.To\u003cOrdinaryPage\u003e(url: \"some/url\")\n    .ValidateHtml(options);\n```\n\n#### Validate with options based on default\n\n```cs\nGo.To\u003cOrdinaryPage\u003e(url: \"some/url\")\n    .ValidateHtml(HtmlValidationOptions.Default.CloneWith(x =\u003e x.ConfigPath = \"another/config.json\"));\n```\n\n### Using `ValidateHtmlAttribute` trigger\n\n`ValidateHtmlAttribute` - the trigger attribute that indicates that the page HTML should be validated on the specified event.\nBy default occurs upon the page object initialization.\nInvokes `ValidateHtml` method using `HtmlValidationOptions.Default` options.\n\nHas `public bool AsWarning { get; set; }` property that gets or sets a value indicating whether to produce a warning instead of assertion exception on validation failure.\nThe default value is `false`.\n\n#### Apply to certain page object\n\n```cs\n[ValidateHtml]\npublic class SomePage : Page\u003c_\u003e\n{\n}\n```\n\n#### Apply to all page objects\n\n```cs\nAtataContext.GlobalConfiguration\n    .Attributes.Global.Add(new ValidateHtmlAttribute { TargetType = typeof(PageObject\u003c\u003e) });\n```\n\n### Using `HtmlValidator`\n\nThis approach is a bit low-level one.\nCan be used without active `AtataContext`.\n\n`HtmlValidator` - uses \"html-validate\" NPM package to execute HTML validation.\nIf required version of \"html-validate\" package is not installed, installs it.\n\n```cs\nHtmlValidator validator = new HtmlValidator(\n    new HtmlValidationOptions()); // HtmlValidationOptions are optional here.\n\nstring html = \"\u003chtml\u003e...\u003c/html\u003e\";\n// string html = webDriver.PageSource;\n\nHtmlValidationResult result = validator.Validate(html);\n\nif (!result.IsSuccessful)\n{\n    string resultMessage = result.Output;\n\n    // TODO: Handle validation failure case.\n}\n```\n\n## Configuration\n\nCheck out [html-validate Configuration](https://html-validate.org/usage/index.html#configuration)\ndocumentation page on how to create config files.\n\nMostly, you can create standard `.htmlvalidate.json` file in the root of a test project with\n\"Copy to Output Directory\" property set to \"Copy if newer\".\n\n## `HtmlValidationOptions` properties\n\n- **`static HtmlValidationOptions Default { get; set; }`**\\\n  Gets or sets the default options.\n- **`string WorkingDirectory { get; set; }`**\\\n  Gets or sets the working directory where HTML and result files should be saved.\n  The default value is `null`, meaning to use `AtataContext.ArtifactsPath`.\n  The other value should be relative to Artifacts directory, for example, a name of subdirectory.\n  The path supports `AtataContext` template variables.\n- **`int? MaxWarnings { get; set; }`**\\\n  Gets or sets the maximum allowed warnings count.\n  The default value is `null`, which means that warnings are allowed.\n  Use `0` to disallow warnings.\n- **`string ConfigPath { get; set; }`**\\\n  Gets or sets the configuration file path (full or relative to `WorkingDirectory`).\n- **`string OutputFormatter { get; set; }`**\\\n  Gets or sets the output formatter name.\n  The default value is `HtmlValidateFormatter.Names.Stylish`.\n  See [`HtmlValidateFormatter.Names`](https://github.com/atata-framework/atata-cli-htmlvalidate/blob/04344a8d4452921537dd9c83d806735e5d4427e7/src/Atata.Cli.HtmlValidate/HtmlValidateFormatter.cs#L39) class for options.\n- **`string ResultFileFormatter { get; set; }`**\\\n  Gets or sets the result file formatter name.\n  The default value is `HtmlValidateFormatter.Names.Codeframe`.\n  See [`HtmlValidateFormatter.Names`](https://github.com/atata-framework/atata-cli-htmlvalidate/blob/04344a8d4452921537dd9c83d806735e5d4427e7/src/Atata.Cli.HtmlValidate/HtmlValidateFormatter.cs#L39) class for options.\n- **`string ResultFileExtension`**\\\n  Gets or sets the result file extension, like \".txt\" or \".json\".\n  The default value is `null`, which means that\n  extension should be resolved automatically corresponding to `ResultFileFormatter` value.\n- **`bool SaveResultToFile`**\\\n  Gets or sets a value indicating whether to save validation result output to file.\n  The default value is `true`.\n- **`HtmlSaveCondition SaveHtmlToFile`**\\\n  Gets or sets a value indicating the condition of HTML file saving.\n  The default value is `HtmlSaveCondition.Invalid`,\n  meaning that HTML file should be saved only when it is not valid.\n  Other available options are: `HtmlSaveCondition.Never` and `HtmlSaveCondition.Always`.\n- **`Encoding Encoding`**\\\n  Gets or sets the encoding to use.\n  The default value is `null`,\n  which means that default encoding should be used.\n- **`ICliCommandFactory CliCommandFactory`**\\\n  Gets or sets the CLI command factory.\n  The default value is `null`,\n  which means that default CLI command factory should be used,\n  which is `ProgramCli.DefaultShellCliCommandFactory`.\n- **`string HtmlValidatePackageVersion`**\\\n  Gets or sets the required version of \"html-validate\" NPM package.\n  The required version will be installed if \"html-validate\" package is not installed or the installed version differs from the required one.\n  The default value is `\"8.29.0\"`.\n  Set `null` to disable the version check and use any pre-installed version.\n\n### Configure default options\n\nIt is possible to configure default `HtmlValidationOptions` upon global initialization method.\n\nChange some default values:\n\n```cs\nHtmlValidationOptions.Default.OutputFormatter = HtmlValidateFormatter.Names.Codeframe;\n```\n\nReset default options completely:\n\n```cs\nHtmlValidationOptions.Default = new HtmlValidationOptions\n{\n    OutputFormatter = HtmlValidateFormatter.Names.Codeframe,\n    SaveResultToFile = false,\n    ConfigPath = \"some/config.json\"\n};\n```\n\n## `HtmlValidationResult` members\n\n### Properties\n\n- **`bool IsSuccessful { get; }`**\\\n  Gets a value indicating whether this result is successful.\n- **`string Output { get; }`**\\\n  Gets the text output of result.\n- **`string HtmlFilePath { get; }`**\\\n  Gets the HTML file path.\n- **`string ResultFilePath { get; }`**\\\n  Gets the result file path.\n\n### Methods\n\n- **`HtmlValidationResult MoveFilesToDirectory(string directory)`**\\\n  Moves the HTML and result files to another directory.\n\n## Validation results\n\nThe results of failed validation using `ValidateHtml` method can be found in few places.\n\nAdditionally original HTML snapshot, which was validated, is saved to Atata Artifacts directory as a file.\n\n### Exception\n\nAn `AssertionException` is thrown with the message similar to:\n\n```\nWrong \"\u003capp\u003e\" page HTML document, which contains errors:\n785a0e99-359a-4905-b490-3a62c61fbf37.html\n  69:22  error  \u003cth\u003e is missing required \"scope\" attribute     element-required-attributes\n  70:22  error  \u003cth\u003e is missing required \"scope\" attribute     element-required-attributes\n  71:22  error  \u003cth\u003e is missing required \"scope\" attribute     element-required-attributes\n  72:22  error  \u003cth\u003e is missing required \"scope\" attribute     element-required-attributes\n  81:26  error  \u003cbutton\u003e is missing required \"type\" attribute  element-required-attributes\n  82:26  error  \u003cbutton\u003e is missing required \"type\" attribute  element-required-attributes\n  83:26  error  \u003cbutton\u003e is missing required \"type\" attribute  element-required-attributes\n\n✖ 7 problems (7 errors, 0 warnings)\n\nMore information:\n  https://html-validate.org/rules/element-required-attributes.html\n```\n\n### Result file\n\nBy default, the result file that is saved to Atata Artifacts directory is generated using \"codeframe\" formatter,\nwhich provides nice detailed report.\n\n```\nerror: \u003cth\u003e is missing required \"scope\" attribute (element-required-attributes) at 785a0e99-359a-4905-b490-3a62c61fbf37.html:69:22:\n  67 |             \u003cthead\u003e\n  68 |                 \u003ctr\u003e\n\u003e 69 |                     \u003cth\u003eName\u003c/th\u003e\n     |                      ^^\n  70 |                     \u003cth\u003ePrice\u003c/th\u003e\n  71 |                     \u003cth\u003eAmount\u003c/th\u003e\n  72 |                     \u003cth\u003e\u003c/th\u003e\nDetails: https://html-validate.org/rules/element-required-attributes.html\n\n\nerror: \u003cth\u003e is missing required \"scope\" attribute (element-required-attributes) at 785a0e99-359a-4905-b490-3a62c61fbf37.html:70:22:\n  68 |                 \u003ctr\u003e\n  69 |                     \u003cth\u003eName\u003c/th\u003e\n\u003e 70 |                     \u003cth\u003ePrice\u003c/th\u003e\n     |                      ^^\n  71 |                     \u003cth\u003eAmount\u003c/th\u003e\n  72 |                     \u003cth\u003e\u003c/th\u003e\n  73 |                 \u003c/tr\u003e\nDetails: https://html-validate.org/rules/element-required-attributes.html\n\n...\n```\n\n### Log\n\nAdditional details of validation execution can be found in Atata log.\n\n```\n...\n2024-04-16 19:06:22.708  INFO \u003e Validate: \"\u003capp\u003e\" page HTML document\n2024-04-16 19:06:22.710 TRACE - \u003e Get page source HTML\n2024-04-16 19:06:22.731 TRACE - \u003c Get page source HTML (0.021s)\n2024-04-16 19:06:22.743 TRACE - HTML saved to file \"785a0e99-359a-4905-b490-3a62c61fbf37.html\"\n2024-04-16 19:06:23.331 TRACE - \u003e Execute html-validate CLI command for \"785a0e99-359a-4905-b490-3a62c61fbf37.html\" with \"stylish\" formatter\n2024-04-16 19:06:24.259 TRACE - \u003c Execute html-validate CLI command for \"785a0e99-359a-4905-b490-3a62c61fbf37.html\" with \"stylish\" formatter (0.927s) \u003e\u003e { IsSuccessful = False }\n2024-04-16 19:06:24.261 TRACE - \u003e Execute html-validate CLI command for \"785a0e99-359a-4905-b490-3a62c61fbf37.html\" with \"codeframe\" formatter\n2024-04-16 19:06:25.116 TRACE - \u003c Execute html-validate CLI command for \"785a0e99-359a-4905-b490-3a62c61fbf37.html\" with \"codeframe\" formatter (0.854s) \u003e\u003e { IsSuccessful = False }\n2024-04-16 19:06:25.120  INFO - HTML validation report saved to file \"785a0e99-359a-4905-b490-3a62c61fbf37.txt\"\n2024-04-16 19:06:25.480 ERROR - Wrong \"\u003capp\u003e\" page HTML document, which contains errors:\n785a0e99-359a-4905-b490-3a62c61fbf37.html\n  69:22  error  \u003cth\u003e is missing required \"scope\" attribute     element-required-attributes\n  70:22  error  \u003cth\u003e is missing required \"scope\" attribute     element-required-attributes\n  71:22  error  \u003cth\u003e is missing required \"scope\" attribute     element-required-attributes\n  72:22  error  \u003cth\u003e is missing required \"scope\" attribute     element-required-attributes\n  81:26  error  \u003cbutton\u003e is missing required \"type\" attribute  element-required-attributes\n  82:26  error  \u003cbutton\u003e is missing required \"type\" attribute  element-required-attributes\n  83:26  error  \u003cbutton\u003e is missing required \"type\" attribute  element-required-attributes\n\n✖ 7 problems (7 errors, 0 warnings)\n\nMore information:\n  https://html-validate.org/rules/element-required-attributes.html\n\n2024-04-16 19:06:25.484  INFO \u003c Validate: \"\u003capp\u003e\" page HTML document (2.775s) \u003e\u003e NUnit.Framework.AssertionException: Wrong \"\u003capp\u003e\" page HTML document, which contains errors...\n...\n```\n\n## Sample project\n\nCheck out [atata-framework/atata-sample-app-tests](https://github.com/atata-framework/atata-sample-app-tests) repository, which contains [`HtmlPageValidationTests`](https://github.com/atata-framework/atata-sample-app-tests/blob/master/test/AtataSampleApp.UITests/HtmlPageValidationTests.cs) test class that validates HTML of some pages.\nIt also contains a sample [`.htmlvalidate.json`](https://github.com/atata-framework/atata-sample-app-tests/blob/master/test/AtataSampleApp.UITests/.htmlvalidate.json) configuration file.\n\n## Feedback\n\nAny feedback, issues and feature requests are welcome.\n\nIf you faced an issue please report it to [Atata.HtmlValidation Issues](https://github.com/atata-framework/atata-htmlvalidation/issues),\n[ask a question on Stack Overflow](https://stackoverflow.com/questions/ask?tags=atata+csharp) using [atata](https://stackoverflow.com/questions/tagged/atata) tag\nor use another [Atata Contact](https://atata.io/contact/) way.\n\n## Thanks\n\nThe library is implemented thanks to the sponsorship of **[Lombiq Technologies](https://lombiq.com/)**.\n\n## SemVer\n\nAtata Framework follows [Semantic Versioning 2.0](https://semver.org/).\nThus backward compatibility is followed and updates within the same major version\n(e.g. from 1.3 to 1.4) should not require code changes.\n\n## License\n\nAtata is an open source software, licensed under the Apache License 2.0.\nSee [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fatata-framework%2Fatata-htmlvalidation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fatata-framework%2Fatata-htmlvalidation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fatata-framework%2Fatata-htmlvalidation/lists"}