Weave Cypress Cloud, UI Coverage, and Cypress Accessibility more closely into the narrative of the docs

.github/ISSUE_TEMPLATE/documentation_request.yml

@@ -10,21 +10,12 @@ body:
         If you have an idea for a new documentation topic, noticed that
         something is not properly documented, or feel that something is
         incorrect with the current documentation, you're in the right place!
-  - type: "input"
-    id: "subject"
-    attributes:
-      label: "Subject"
-      description:
-        "What is the subject (guides, api, plugins, examples, faq) of this request?"
-      placeholder: "Guides"
-    validations:
-      required: true
   - type: "textarea"
     id: "description"
     attributes:
       label: "Description"
       description:
         "What about the subject's documentation should be added or changed?"
-      placeholder: "Update Guides with new 'Migrating to Cypress' page"
+      placeholder: "Update with new 'Migrating to Cypress' page"
     validations:
       required: true

CONTRIBUTING.md

@@ -24,12 +24,6 @@ Thanks for taking the time to contribute! :smile:
     - [Pull Requests](#pull-requests)
     - [Contributor License Agreement](#contributor-license-agreement)
   - [Deployment](#deployment)
-    - [Trigger workflow build](#trigger-workflow-build)
-
-## Code of Conduct
-
-All contributors are expected to abide by our
-[Code of Conduct](https://github.com/cypress-io/cypress/blob/develop/CODE_OF_CONDUCT.md).
 
 ## Writing Documentation
 
@@ -55,29 +49,23 @@ If you are using VS Code, download the
 [MDX extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx)
 to get full editor support for MDX files.
 
-#### Admonitions
-
-Use [Admonitions](https://docusaurus.io/docs/markdown-features/admonitions) to
-grab the reader's attention with a blurb.
-
 #### Images
 
 If you are starting a new page and want to add images, add a new folder to
 [`static/img`](/static/img). For example when adding a new "Code Coverage" page
-to `guides/tooling`, I have created new folder `assets/img/guides/tooling` and
+to `app/tooling`, I have created new folder `assets/img/app/tooling` and
 copied an image there called `coverage-object.png`. Within the markdown, I can
 include the image using the
 [`<DocsImage />` component](/src/components/docs-image).
 
 ```jsx
 <DocsImage
-  src="/img/guides/tooling/coverage-object.png"
+  src="/img/app/tooling/coverage-object.png"
   alt="code coverage object"
 />
 ```
 
-Typically you should include the `alt` and `title` attributes to give the user
-more information about the image.
+You should always include the `alt` and `title` attributes to ensure the image is accessible and to give the user more information about the image.
 
 #### Videos
 
@@ -170,30 +158,6 @@ We also opened an [issue](https://github.com/facebook/docusaurus/issues/7946) to
 add this as a feature to Docusaurus, so if this gets implemented this patch can
 go away.
 
-### Writing the Changelog
-
-When adding to the [Changelog](/docs/guides/references/changelog.mdx), create a
-new section with the title as the version number on top of the previous section.
-Be sure to follow the category structure defined below (in this order). Each
-bullet point in the list should _always_ be associated to an issue on the
-[`cypress`](https://github.com/cypress-io/cypress) repo and link to that issue
-(except for Documentation changes).
-
-#### Categories
-
-- **Summary** - If it is a large release, you may write a summary explaining
-  what the point of this release is (mostly used for breaking releases)
-- **Breaking Changes** - The users current implementation of Cypress may break
-  after updating.
-- **Deprecations** - Features have been deprecated, but will not break after
-  updating.
-- **Features** - A new feature
-- **Bugfixes** - A bug existed in Cypress and a PR fixed the issue
-- **Misc** - Not a feature or bugfix, but work that was done. May be internal
-  work that was done and associated with an issue
-- **Documentation Changes** - our docs were updated based on behavior changes in
-  release
-
 ## Committing Code
 
 ### Pull Requests
@@ -234,9 +198,7 @@ open a pull request (PR) from your repo to the
 ### Contributor License Agreement
 
 We use a [`cla-assistant.io`](https://cla-assistant.io/) web hook to make sure
-every contributor assigns the rights of their contribution to Cypress.io. If you
-want to read the CLA agreement, its text is in this
-[gist](https://gist.github.com/bahmutov/cf22bc6c6b55219d0f9a76d04981f7ae).
+every contributor assigns the rights of their contribution to Cypress.io.
 
 After making a [pull request](#pull-requests), the CLA assistant will add a
 review comment. Click on the link and accept the CLA. That's it!
@@ -246,20 +208,3 @@ review comment. Click on the link and accept the CLA. That's it!
 We will try to review and merge pull requests as fast as possible. After
 merging, the changes will be made available on the official
 [https://docs.cypress.io](https://docs.cypress.io) website.
-
-### Trigger workflow build
-
-Due to CircleCI API limitations, you cannot trigger a workflow build using the
-API. Thus if you need to build, test and deploy `your-branch` branch for
-example, your best bet is to create an empty GitHub commit in the
-[cypress-io/cypress-documentation](https://github.com/cypress-io/cypress-documentation)
-repository in the `your-branch` branch. We have added
-[make-empty-github-commit](https://github.com/bahmutov/make-empty-github-commit)
-as a dev dependency and set it as `make-empty-commit` NPM script in the
-[package.json](package.json).
-
-To trigger production rebuild and redeploy, use personal GitHub token and run:
-
-```shell
-GITHUB_TOKEN=<your token> npm run make-empty-commit -- --message "trigger deploy" --branch main
-```

README.md

@@ -1,8 +1,5 @@
 # Cypress Documentation [![Discord chat](https://img.shields.io/badge/chat-on%20Discord-brightgreen)](https://on.cypress.io/discord) [![first-timers-only](http://img.shields.io/badge/first--timers--only-friendly-blue.svg)](https://github.com/cypress-io/cypress-documentation/labels/first-timers-only)
 
-The code for Cypress Documentation including Guides, API, Examples, Cypress
-Cloud & FAQ found at https://docs.cypress.io.
-
 ![Cypress Documentation Preview](/static/img/cypress-docs.png)
 
 ## CI status

docs/accessibility/changelog.mdx

@@ -0,0 +1,82 @@
+---
+title: 'Changelog | Cypress Accessibility'
+description: 'Stay up to date with the latest features, improvements, and bug fixes for Cypress Accessibility.'
+sidebar_label: Changelog
+sidebar_position: 200
+---
+
+# Changelog
+
+## Week of 9/30/2024
+
+- Cypress Accessibility results are now included in Slack messages alongside test results. [Learn more about our Slack integration here](https://on.cypress.io/slack-integration).
+
+## Week of 9/20/2024
+
+- A minor bugfix was released for score calculations, to fix a scenario where some snapshots could be counted more than once if they appeared in multiple tests. This may result in a small difference in the total score for runs before and after the change.
+- Documentation updates to reflect recently released features and capabilities.
+
+## Week of 9/9/2024
+
+- We have introduced the new "Rules" tab for all users. This allows you to more easily review the outcome of all the rules that were tested for, across the entire run, and see which rules have the most failing elements. This also helps you understand the exact effect of any underlying configuration on rule outcomes.
+- We have introduced new element statuses, beyond just failures. This allows Cypress Accessibility to surface any inconclusive or "manual review" items from Axe Core, as well as track and display elements whose results were explicitly ignored. Learn more in the [run-level reports](/accessibility/core-concepts/run-level-reports) [Elements section](/accessibility/core-concepts/run-level-reports#Elements).
+- Elements ignored by configuration will have results captured, but these results will not affect your score. This ensures you can use filters to peek behind the curtain and understand exactly what is being excluded from a given run's results.
+- The Detail View that displays failing elements will now also display inconclusive and (optionally) ignored elements for each rule. Inconclusive and ignored elements have distinct orange and gray icons and highlights respectively.
+
+## Week of 8/19/2024
+
+- iFrames are now supported for accessibility checks. iFrame processing is _opt-in_ for existing customers, but new customers will begin with iFrames enabled and can choose to opt out instead. This is to avoid disrupting existing pipelines, especially because iFrame content is not _always_ something you want to include in your reports.
+- Cypress Accessibility results will now appear in [GitHub](https://on.cypress.io/github-integration), [GitLab](https://on.cypress.io/gitlab-integration) and [Bitbucket](https://on.cypress.io/bitbucket-integration) pull request and merge request comments alongside test results. Integrations can be installed and comments can be enabled in Project Settings.
+
+## Week of 8/5/2024
+
+- We now support fetching Accessibility results from CircleCI workflows with the [Results API](/accessibility/results-api).
+
+## Week of 7/29/2024
+
+- Fetching results in Azure and Jenkins is now supported in the new [Results API](/accessibility/results-api), which enables you to programmatically fetch your run's Accessibility results in a CI environment.
+
+## Week of 7/15/2024
+
+- The new [Results API](/accessibility/results-api), which enables you to programmatically fetch your run's Accessibility results in a CI environment, now supports fetching results in GitLab CI workflows.
+
+## Week of 6/24/2024
+
+- We have added the new [Results API](/accessibility/results-api) which enables you to programmatically fetch your run's Accessibility results in a CI environment. This allows you to review the results within CI and to determine if the results are acceptable or need to be addressed before code changes can merge.
+- View [configuration information for each run](/accessibility/configuration/overview#Viewing-Configuration-for-a-Run) in the properties tab. There, you'll find the configuration set for the project at the start of the run. This will help you understand what factors might be driving a score change. This helps distinguish config criteria changes from other factors such as changes to your application, tests, Cypress versions, and more.
+
+## Week of 5/20/2024
+
+- Shadow DOM elements are now visible and highlighted in A11y report snapshots. By highlighting shadow DOM elements in snapshots, developers can identify and address all accessibility violations, including those within encapsulated components, thus enhancing the overall accessibility of the web application.
+- You can now click directly into the accessibility report from any respective run from the "Latest Runs" page in Cypress Cloud. This improvement streamlines access and navigation to accessibility reports, saving you time and reducing the number of steps needed to view the details.
+- We've added the ability to configure and customize your Accessibility report in Project Settings. You can set configuration through our editor equipped with linting and IntelliSense code completion. Control what should be tested or ignored in your score calculations to ensure your team is capturing what's relevant to your organization's goals.
+
+## Week of 4/15/2024
+
+- We've added full depth axe-core® details for each element flagged with an accessibility violation, providing comprehensive context to help developers accurately identify and resolve issues.
+
+## Week of 3/25/2024
+
+- The new Violation Severity Breakdown displays a small bar graph indicating the severity level of accessibility violations across the entire run, or on the level of individual pages or components. This gives users more information at a glance about what pages have the most severe problems, and the overall makeup of their accessibility report. Pages with more severe problems will now be more obvious when scanning the report, helping users decide what pages need more investigation or which pages have the fewest problems.
+
+## Week of 3/18/2024
+
+- You can now refine your Views list by severity or specific rule sets. For instance, isolate pages featuring "Critical" violations only, or focus solely on WCAG 2.1 A violations. If your project has varying levels of accessibility, filtering pages or components with specific types of violations can serve as an initial step to comprehend and prioritize areas with the most severe issues.
+- Cypress will now conduct accessibility checks within the Shadow DOM on all runs, expanding the accessibility testing scope.
+
+## Week of 2/25/2024
+
+- We've introduced text filtering so that users can filter the "Views" list by name, making it effortless to search and locate specific items.
+- To improve clarity and context, we've also implemented a tooltip-style feature that displays the position of the highlighted elements. This means that when an accessibility violation is reported and is associated with a specific element on the screen, it's a lot easier to locate.
+
+## Week of 1/15/2024
+
+- We've introduced a new feature that streamlines accessibility management - the aggregation of all violations into a single comprehensive report. Look for the "View all" link next to the violations count at the top of the accessibility tab. This will show you all violations detected across an entire run, regardless of what page or component they are detected on.
+
+## Week of 12/31/2023
+
+- Users can now discover and address accessibility violations swiftly by utilizing the newly integrated "Print Elements to Console" button within your browser's developer tools.
+
+## Week of 12/17/2023
+
+- Users can now view a detailed breakdown of the total number of Views (pages and/or components) and Violations detected during a specific run.

docs/accessibility/configuration/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Configuration",
+  "position": 30
+}

docs/accessibility/configuration/axe-core-configuration.mdx

@@ -0,0 +1,32 @@
+---
+title: 'Axe Core® configuration | Cypress Accessibility'
+description: 'Configuration for Axe-Core® rules can be configured.'
+sidebar_label: 'Axe Core® configuration'
+---
+
+# Axe Core® configuration
+
+<AccessibilityAddon />
+
+Configuration for Axe-Core® rules is available through your Account Executive. We we are happy to have a call with you to dial in your report config to make sure you are getting the most useful reports possible, and we find this onboarding very effective.
+
+In most cases, configuration of these rules as they run in Cypress Cloud isn't needed, because your implementation of any policies about what should "fail a build" is handled using the [Accessibility Results API](/accessibility/results-api), where you have full control over how to parse the results and what rules need to be reacted to. Keeping the results in Cypress Cloud broad helps you to still be able to see and understand all of the accessibility information, even if only a subset of the results would be considered blocking.
+
+**Note.** Certain Axe Core® rules are off by default. Here are the rules that are currently either ignored by configuration, or for which results cannot be detected.
+
+- `Elements must meet minimum color contrast ratio thresholds`
+  - This is off by default. This is both the slowest rule in the Axe Core® ruleset, and the one that can have the highest percentage of false positives or incomplete checks.
+  - It does work perfectly in many projects, so we are happy to turn this on for you if requested, so that you can see the results.
+- `<video> or <audio> elements must not play automatically`
+  - Ignored because Test Replay does not yet capture the metadata to check this
+- `Delayed refresh under 20 hours must not be used`
+  - Ignored because Test Replay does not collect the metadata for this
+
+## Component Testing
+
+Cypress Accessibility works great with component testing. In addition the the rules that are off by default, "page-level" rules do not run for component tests, since a component is usually a fragment mounted in an empty page that would not be expected to have things like headings or a `main` element.
+
+## Updates to the Axe Core® library
+
+Updates to the Axe Core® library are released several times each year. While Cypress does not commit to updating our internal Axe Core® version within a specific timeframe, we will always wait at least 30 days before making an update.
+Since some updates introduce new rules or address bugs that change how issues are detected, this buffer is intended to give you time to make changes in your use of our [Results API](/accessibility/results-api) if needed. Axe Core® releases can be tracked [in GitHub](https://github.com/dequelabs/axe-core/releases).