# Cypress Documentation
# Source: https://raw.githubusercontent.com/cypress-io/cypress-documentation/main/docs/api/commands/url.mdx
# Path: docs/api/commands/url.mdx

---
title: 'url | Cypress Documentation'
description: Get the current URL of the page that is currently active in Cypress.
sidebar_label: url
e2eSpecific: true
slug: /api/commands/url
---

<ProductHeading product="app" />

# url

Get the current URL of the page that is currently active.

:::info

This is an alias of [`cy.location('href')`](/api/commands/location)

:::

## Syntax

```javascript
cy.url()
cy.url(options)
```

### Usage

<Icon name="check-circle" color="green" /> **Correct Usage**

```javascript
cy.url() // Yields the current URL as a string
```

### Arguments

<Icon name="angle-right" /> **options _(Object)_**

Pass in an options object to change the default behavior of `cy.url()`.

**cy.url( _options_ )**

| Option    | Default                                                           | Description                                                                         |
| --------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `decode`  | `false`                                                           | Decode URL                                                                          |
| `log`     | `true`                                                            | Displays the command in the [Command log](/app/core-concepts/open-mode#Command-Log) |
| `timeout` | [`defaultCommandTimeout`](/app/references/configuration#Timeouts) | Time to wait for `cy.url()` to resolve before [timing out](#Timeouts)               |

<HeaderYields />

- `cy.url()` yields the current URL as a string.
- `cy.url()` is a query, and it is _safe_ to chain further commands.

## Examples

### No Args

#### Assert the URL is `http://localhost:8000/users/1/edit`

```javascript
// clicking the anchor causes the browser to follow the link
cy.get('#user-edit a').click()
cy.url().should('include', '/users/1/edit') // => true
cy.url().should('eq', 'http://localhost:8000/users/1/edit') // => true
```

### `decode` option

When the URL contains non-ASCII characters, use the `decode` option.

```javascript
// For the curious, '사랑' means 'love' in Korean.
cy.url({ decode: true }).should('contain', '사랑')
```

## Notes

### Href Shorthand

#### URL is an alias for `cy.location('href')`

`cy.url()` uses `href` under the hood.

```javascript
cy.url() // these yield the same string
cy.location('href') // these yield the same string
```

### Differences

#### URL versus href

Given the remote URL, `http://localhost:8000/index.html`, all 3 of these
assertions are the same.

```javascript
cy.location('href').should('include', '/index.html')

cy.location().its('href').should('include', '/index.html')

cy.url().should('include', '/index.html')
```

`href` and `toString` come from the `window.location` spec.

But you may be wondering where the URL property comes from. Per the
`window.location` spec, there actually isn't a URL property on the `location`
object.

`cy.url()` exists because it's what most developers naturally assume would
return them the full current URL. We almost never refer to the URL as an `href`.

#### Hardcoded versus using the configuration object

Instead of hard-coding the URL used in the assertion, we recommend you define a
`baseUrl` in your [Cypress configuration](/app/references/configuration). For
more details on why, see our Best Practices guide on
[setting a global `baseUrl`](/app/core-concepts/best-practices#Setting-a-Global-baseUrl).

Given the remote URL, `http://localhost:8000/index.html`, and the baseUrl,
`http://localhost:8000`, these assertions are the same.

```javascript
cy.url().should('eq', 'http://localhost:8000/index.html')
cy.url().should('eq', Cypress.config().baseUrl + '/index.html') // tests won't fail in case the port changes
```

#### Assert that the url contains "#users/new"

```javascript
cy.url().should('contain', '#users/new')
```

## Rules

<HeaderRequirements />

- `cy.url()` requires being chained off of `cy`.

<HeaderAssertions />

- `cy.url()` will automatically [retry](/app/core-concepts/retry-ability)
  until all chained assertions have passed

<HeaderTimeouts />

- `cy.url()` can time out waiting for assertions you've added to pass.

## Command Log

The commands above will display in the Command Log as:

<DocsImage
  src="/img/api/url/test-url-of-website-or-web-application.png"
  alt="Command Log url"
/>

When clicking on URL within the Command Log, the console outputs the following:

<DocsImage
  src="/img/api/url/console-log-of-browser-url-string.png"
  alt="Console Log url"
/>

## History

| Version                                    | Changes                  |
| ------------------------------------------ | ------------------------ |
| [8.4.0](/app/references/changelog#8-4-0)   | `decode` option added    |
| [< 0.3.3](/app/references/changelog#0-3-3) | `cy.url()` command added |

## See also

- [`cy.hash()`](/api/commands/hash)
- [`cy.location()`](/api/commands/location)