Skip to content

TAGS.md

Latest commit

 

History

History
373 lines (266 loc) · 7.21 KB

TAGS.md

File metadata and controls

373 lines (266 loc) · 7.21 KB

Tags

The Cypress documentation uses Hexo to convert Markdown documents to static HTML.

Hexo ships with lots of tags that extend Markdown with extra features.

Here's documentation for all the custom tags that we've created.

Common Hexo tags

We didn't create the tags in this section—they ship with Hexo—but they're used all over the docs so here's the lowdown.

img

Insert the markup for an inline image.

{% img /img/examples/name-of-file.jpg "alt text describing img" %}
<img src="/img/examples/name-of-file.jpg" alt="alt text describing img">

Custom Cypress tags

We've created plenty of custom tags that Hexo loads from the libs/tags folder. Use 'em 'cos they give the docs a consistent look and feel.

assertions

Describe what assertions can be chained off a command.

{% assertions none cy.clearCookie %}
<ul>
  <li><p><code>cy.clearCookie()</code> cannot have any assertions chained.</p></li>
</ul>

The following assertions are supported:

  • actions
  • existence
  • its
  • none
  • once
  • retry
  • utility
  • wait

changelog

Builds a single changelog file from the contents of source/_changelogs

fa

Insert a specific Font Awesome icon by name.

{% fa fa-check-circle green %}

Use these icons to highlight important statements.

**{% fa fa-check-circle green %} Correct Usage**

**{% fa fa-exclamation-triangle red %} Incorrect Usage**

**{% fa fa-angle-right %} value** ***(String)***

helper_icon

Insert a commonly used icon by name.

{% helper_icon yields %}

The following icons are supported:

  • assertions
  • requirements
  • timeout
  • yields

issue

Link to an issue on Cypress's GitHub repository.

{% issue 74 "not currently supported" %}

note

Display a block of content that visually stands out from the body of the text.

Most often used to call out warnings, useful info, and tips.

{% note warning 'Anti-Pattern' %}
We do not recommend starting a web server using `cy.task()`. Read about {% url 'best practices' best-practices#Web-Servers %} here.
{% endnote %}

The first argument is required: it's used to style the block and add an appropriate icon. Use one of the following values:

  • info
  • warning
  • success
  • danger
  • bolt

The second argument is optional: if present it's used as the title of the block.

open_an_issue

Link to the issue creation page on Cypress's GitHub repository.

{% open_an_issue %}

Typically used to make it easier for users to open issues.

At the moment, `mouseover` and `mouseout` events are *not* fired. {% open_an_issue %} if you need this to be fixed.

partial

Include the content of another file inline.

{% partial then_should_difference %}

requirements

Describe a command's requirements.

{% requirements parent cy.clearCookie %}
<ul>
  <li><p><code>cy.clearCookie()</code> requires being chained off of <code>cy</code>.</p></li>
</ul>

The following requirements are supported:

  • none
  • parent
  • child
  • dom
  • dual
  • dual_existence
  • dual_existence_single_dom
  • clearability
  • blurability
  • clearability
  • focusability
  • checkability
  • selectability
  • scrollability
  • submitability
  • spread
  • exec
  • task
  • read_file
  • write_file
  • page
  • tick
  • request

timeouts

Describe a timeout.

{% timeouts existence cy.get %}
<ul>
  <li><p><code>cy.get()</code> can time out waiting for the element(s) to <a href="/guides/core-concepts/introduction-to-cypress.html#Default-Assertions">exist in the DOM</a>.</p></li>
</ul>

Typically used inside the Timeouts section when documenting a command.

## Timeouts {% helper_icon timeout %}

{% timeouts existence cy.get %}

The following timeouts are supported:

  • assertions
  • actions
  • existence
  • automation
  • its
  • exec
  • task
  • none
  • page
  • request
  • wait
  • promises
  • timeouts

url

Generate a link.

{% url `.and()` and %}
{% url `.should()` should#Notes %}
{% url 'Read about why' why-cypress %}
{% url http://foo.com %}

urlHash

Generate a link to an anchor.

{% urlHash 'Standard Output' Standard-Output %}
<a href="#Standard-Output">Standard Output</a>

usage_options

Describe the usage of a command option.

Typically used when documenting the options object inside the Arguments section.

## Arguments

**{% fa fa-angle-right %} options**  ***(Object)***

Pass in an options object to change the default behavior of `.blur`.

Option | Default | Description
--- | --- | ---
`log` | `true` | {% usage_options log %}
`timeout` | {% url `defaultCommandTimeout` configuration#Timeouts %} | {% usage_options timeout .blur %}

The following usages are supported:

  • log
  • force
  • multiple
  • timeout

user

Link to a GitHub profile.

Typically used to give attribution to someone who has contributed to Cypress.

Contributed by {% user brian-mann %}.

video

Embed a video.

{% video vimeo 240554515 %}
{% video youtube 5XQOK0v_YRE %}
{% video local /img/snippets/selector-playground.mp4 %}

yields

Describe what a command yields.

{% yields sets_subject cy.readFile 'yields the contents of the file' %}
<ul>
  <li><p><code>cy.readFile()</code> yields the contents of the file</p></li>
</ul>

Typically used inside the Yields section when documenting a command.

## Yields {% helper_icon yields %}

{% yields sets_subject cy.readFile 'yields the contents of the file' %}

The following yields are supported:

  • same_subject
  • changes_subject
  • maybe_changes_subject
  • changes_dom_subject
  • changes_dom_subject_or_subjects
  • sets_dom_subject
  • sets_subject
  • null
  • null_alias
  • assertion_indeterminate