Base URL configuration in Cypress - Deep Dive

Overview - Base URL configuration

What is it?

Base URL configuration in Cypress is setting a main web address that your tests will use as a starting point. Instead of writing the full website address in every test, you define it once. This makes tests shorter and easier to read. It also helps when you want to run tests on different environments like development or production.

Why it matters

Without base URL configuration, you would have to write the full website address in every test. This is repetitive and error-prone. If the website address changes, you would need to update every test manually. Base URL configuration saves time, reduces mistakes, and makes switching between environments simple and safe.

Where it fits

Before learning base URL configuration, you should understand basic Cypress test writing and how to visit web pages in tests. After this, you can learn about environment variables and advanced configuration to run tests in different setups automatically.

Mental Model

Core Idea

Base URL configuration sets a single main web address so tests can use short paths instead of full URLs.

Think of it like...

It's like setting your home address in your phone contacts so you only need to type the street name when giving directions, instead of the full address every time.

┌─────────────────────────────┐
│ Cypress Test Configuration   │
│                             │
│  Base URL: https://example.com │
│                             │
│  Test command: cy.visit('/login') │
│                             │
│  Full URL used: https://example.com/login │
└─────────────────────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding Cypress cy.visit()

Concept: Learn how Cypress opens web pages using cy.visit() with full URLs.

In Cypress, cy.visit() is used to open a web page during a test. You can pass a full URL like cy.visit('https://example.com/login'). This tells Cypress exactly where to go.

Result

The browser opens the page at https://example.com/login during the test.

Knowing how cy.visit() works with full URLs is the base for understanding why base URL configuration helps simplify tests.

2

Foundation

Problems with full URLs in tests

Concept: See why writing full URLs in every test is inefficient and error-prone.

If you write cy.visit('https://example.com/login') in every test, it becomes repetitive. If the website address changes, you must update all tests. This wastes time and risks missing some updates.

Result

Tests become harder to maintain and more fragile when URLs change.

Recognizing this problem motivates the need for a better way to manage URLs in tests.

3

Intermediate

Setting baseUrl in cypress.config.js

🤔Before reading on: do you think setting baseUrl affects how cy.visit() works with relative paths? Commit to your answer.

Concept: Learn how to define a baseUrl in Cypress configuration to use relative paths in tests.

In the cypress.config.js file, you can add a baseUrl property like this: export default { e2e: { baseUrl: 'https://example.com' } } Now, in tests, you can write cy.visit('/login') instead of the full URL.

Result

Cypress automatically combines baseUrl and the relative path to open https://example.com/login.

Understanding baseUrl lets you write cleaner tests and easily switch environments by changing one place.

4

Intermediate

Using relative URLs in tests

🤔Before reading on: do you think cy.visit('/') will open the baseUrl homepage or cause an error? Commit to your answer.

Concept: Practice using relative URLs in tests after setting baseUrl.

With baseUrl set, cy.visit('/') opens the homepage at the base URL. You can also visit other pages like cy.visit('/dashboard'). This keeps tests short and focused on page paths.

Result

Tests run successfully visiting pages relative to the base URL.

Knowing relative URLs work with baseUrl helps you write flexible and readable tests.

5

Intermediate

Overriding baseUrl in individual tests

🤔Before reading on: can you override baseUrl for a single cy.visit() call? Commit to your answer.

Concept: Learn how to use full URLs in tests even when baseUrl is set.

If you want to visit a page outside the baseUrl, you can still pass a full URL to cy.visit(), like cy.visit('https://other-site.com/page'). This overrides the baseUrl for that call only.

Result

Cypress opens the exact URL you specify, ignoring baseUrl for that visit.

Knowing you can override baseUrl per visit adds flexibility for testing multiple sites or external pages.

6

Advanced

Configuring baseUrl for multiple environments

🤔Before reading on: do you think baseUrl can be changed automatically for different test runs? Commit to your answer.

Concept: Use environment variables or config files to set baseUrl dynamically for dev, staging, or production.

You can set baseUrl differently by environment using command line or config files: // cypress.config.js export default { e2e: { baseUrl: process.env.BASE_URL || 'https://default.com' } } Run tests with BASE_URL=https://staging.example.com npx cypress run This way, tests run against the right environment without code changes.

Result

Tests automatically target the correct website environment based on how you run them.

Dynamic baseUrl configuration enables safe, automated testing across multiple environments.

7

Expert

Base URL impact on test reliability and speed

🤔Before reading on: does baseUrl configuration affect test execution speed or flakiness? Commit to your answer.

Concept: Understand how proper baseUrl setup reduces errors and speeds up test writing and maintenance.

Using baseUrl reduces hard-coded URLs, lowering typos and broken links in tests. It also makes tests easier to update and share. This leads to fewer flaky tests caused by wrong URLs and faster test development cycles.

Result

More reliable and maintainable test suites with less manual work.

Recognizing baseUrl's role beyond convenience helps prioritize good configuration for robust testing.

Under the Hood

Cypress reads the baseUrl from its configuration before running tests. When cy.visit() is called with a relative path, Cypress concatenates baseUrl and the path to form a full URL. This happens internally before the browser navigates. If a full URL is given, Cypress uses it directly, ignoring baseUrl.

Why designed this way?

This design separates configuration from test code, making tests cleaner and easier to maintain. It also supports multiple environments by changing one config value instead of many test files. Alternatives like hardcoding URLs in tests were error-prone and inflexible.

┌───────────────┐       ┌───────────────┐       ┌───────────────┐
│ cypress.config │──────▶│ baseUrl value │──────▶│ URL builder   │
│ .js file      │       │ 'https://...' │       │ concatenates  │
└───────────────┘       └───────────────┘       │ baseUrl +    │
                                                  │ relative path │
                                                  └──────┬────────┘
                                                         │
                                                         ▼
                                               ┌─────────────────┐
                                               │ Browser visits   │
                                               │ full URL        │
                                               └─────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does setting baseUrl mean you cannot visit full URLs in tests? Commit yes or no.

Common Belief: Once baseUrl is set, you must always use relative paths in cy.visit().

Reality: You can still use full URLs in cy.visit() to override baseUrl for specific visits.

Why it matters: Believing this limits test flexibility, preventing testing of external or different sites when needed.

Quick: Does baseUrl automatically change when you run tests in different environments? Commit yes or no.

Common Belief: baseUrl changes automatically based on environment without extra setup.

Reality: You must configure baseUrl manually or use environment variables to switch it per environment.

Why it matters: Assuming automatic switching causes tests to run against wrong sites, leading to false failures or data issues.

Quick: Does using baseUrl make tests run faster? Commit yes or no.

Common Belief: baseUrl configuration speeds up test execution time.

Reality: baseUrl does not affect browser speed but improves test writing speed and reduces errors.

Why it matters: Misunderstanding this may cause misplaced expectations about performance improvements.

Quick: Is baseUrl required for all Cypress tests? Commit yes or no.

Common Belief: You must always set baseUrl to write Cypress tests.

Reality: baseUrl is optional; tests can use full URLs without it, but baseUrl improves maintainability.

Why it matters: Thinking baseUrl is mandatory may confuse beginners and discourage simple test writing.

Expert Zone

1

baseUrl concatenation respects trailing slashes, so misconfigured slashes can cause double slashes or missing slashes in URLs.

2

Using baseUrl with environment variables requires careful handling to avoid undefined or empty values causing test failures.

3

baseUrl affects cy.visit() but not other commands like cy.request(), which need full URLs or separate configuration.

When NOT to use

Avoid baseUrl when testing multiple unrelated domains in the same test suite; instead, use full URLs per visit. Also, for API testing with cy.request(), baseUrl does not apply, so configure request URLs explicitly.

Production Patterns

Teams use baseUrl with environment-specific config files or CI/CD environment variables to run tests against dev, staging, and production without code changes. They combine baseUrl with custom commands to build URLs dynamically and handle multi-domain testing by overriding baseUrl per test.

Connections

Environment Variables

builds-on

Knowing how to use environment variables to set baseUrl dynamically helps automate testing across different deployment environments.

Page Object Model

complements

Using baseUrl with page objects allows tests to focus on page behavior without repeating full URLs, improving code reuse and clarity.

Network Routing in Web Servers

similar pattern

Base URL configuration in testing is like setting a root path in web server routing, simplifying how requests are resolved to resources.

Common Pitfalls

#1 Forgetting to set baseUrl and writing relative paths in cy.visit(), causing test failures.

Wrong approach:

cy.visit('/login') // without baseUrl set

Correct approach:

Set baseUrl in cypress.config.js or use full URL: cy.visit('https://example.com/login')

Root cause:

Misunderstanding that relative paths need baseUrl to resolve correctly.

#2 Setting baseUrl with a trailing slash and using cy.visit() with a leading slash, causing double slashes in URL.

Wrong approach:

baseUrl: 'https://example.com/' and cy.visit('/login')

Correct approach:

baseUrl: 'https://example.com' and cy.visit('/login')

Root cause:

Not knowing how URL concatenation handles slashes leads to malformed URLs.

#3 Hardcoding baseUrl in tests instead of configuration, making environment switching hard.

Wrong approach:

cy.visit('https://staging.example.com/login') in test code

Correct approach:

Set baseUrl via environment variable or config and use cy.visit('/login')

Root cause:

Lack of separation between test logic and environment configuration.

Key Takeaways

Base URL configuration lets you write shorter, cleaner tests by setting a main website address once.

It reduces errors and maintenance effort by avoiding repeated full URLs in test code.

You can override baseUrl per visit by using full URLs when needed for flexibility.

Dynamic baseUrl setup with environment variables enables safe testing across multiple environments.

Understanding baseUrl internals helps prevent common URL mistakes and improves test reliability.