Skip to content

Latest commit

 

History

History
460 lines (320 loc) · 9 KB

TAGS.md

File metadata and controls

460 lines (320 loc) · 9 KB
Raw

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.

markdown

If you have text in YAML file with Markdown tags, and you want to render it from the SWIG template, use {% markdown %} tag:

<div class="plugin-type-description">{% markdown %}{{ pluginType.description }}{% endmarkdown %}</div>

raw

If certain content is causing processing issues in your posts, wrap it with the raw tag to avoid rendering errors.

{% raw %}
content
{% endraw %}

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.

aliases

Describe other aliases for a command.

{% aliases contain includes contains %}
<br>
<small class="aliases">
  <strong>Aliases: </strong>contain, includes, contains
</small>

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

badge

Displays a pill shaped badge around text.

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

history

Displays a collapsible table describing changes to the command from past Cypress versions.

{% history %}
2.0.0 | Foo deprecated, now use bar
1.0.0 | Commmand added
{% endhistory %}
<details class="history">
  <summary>
    <h1 id="History" class="article-heading">
      <i class="fa fa-chevron-down history-disclosure"></i>
      History
    </h1>
  </summary>
  | Version | Changes |
  | --- | --- |
  | 2.0.0 | Foo deprecated, now use bar
  | 1.0.0 | Commmand introduced
</details>

imgTag

Display an image from within themese/cypress/source directory.

% imgTag "img/api/coordinates-diagram.jpg" "alt text" ["css-class"] %}
<img src="/img/api/coordinates-diagram.jpg" alt="alt text" class="css-class" />

issue

Link to an issue on Cypress's GitHub repository.

{% issue 74 %}
<a href="https://github.com/cypress-io/cypress/issues/74" target="_blank">
  #74
</a>
{% issue 74 "not currently supported" %}
<a href="https://github.com/cypress-io/cypress/issues/74" target="_blank">
  not currently supported
</a>

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 %}

PR

Link to a specific PR from Cypress' GitHub repo.

{% PR 75 "See PR" %}
<a href="https://github.com/cypress-io/cypress/pull/75" target="_blank">
  See PR
</a>
{% PR 75 %}
<a href="https://github.com/cypress-io/cypress/pull/75" target="_blank">
  #75
</a>

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>

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 %}

url

Generate a link. Relative links are validated to exist within the Cypress documentation automatically and will error if not found.

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

urlHash

Generate a link to an anchor from within the same page. The hash is validated to exist within its own page and will error if not found.

{% 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