Skip to main content

Testing localhost with mabl Link

Eva Ferreira
  • Updated

With mabl Link, you can run browser tests in the mabl cloud against a service on a local machine, including localhost and 127.0.0.1, without deploying it or exposing it to the internet. Use this setup to run tests in parallel, with full diagnostics from mabl cloud runs, against a local development build.

This article explains how to test localhost with mabl Link.

Before you start

A cloud test reaches localhost on the machine where its Link tunnel runs, so choose the tunnel that runs on the machine with the service:

  • To test a service on your own computer, the easiest option is a personal Link tunnel. Start one from the mabl desktop app or the mabl CLI, and route your run through your computer. You don't need a shared Link Agent or an environment change.
  • To test a service on a shared machine, such as a build server, run a Link Agent on that machine and configure the environment to use its tunnel. If you haven't set up the Link Agent yet, see Link Agent setup.

Run tests

Configure your tests to run against the local URL, such as http://localhost:3000, and run them in the mabl cloud. When a cloud test goes to a loopback address, such as localhost or 127.0.0.1, the request travels through the Link tunnel to the machine where the tunnel runs and connects to your local service.

Note

Reaching localhost over Link is supported for browser tests on Chromium-based browsers (Chrome and Edge) and Firefox. For tests running on Safari, you need to use an alias for localhost to connect to your local service. See Add an alias for localhost below.

Add an alias for localhost

To test localhost with mabl Link on a Safari (WebKit) browser, add an alias for localhost in the hosts file of the system where the Link Agent is running:

  • Linux and macOS: edit the /etc/hosts file
  • Windows: edit the C:\Windows\System32\Drivers\etc\hosts file

The alias should point to the same IP as localhost. In the hosts file, look for a line similar to the following:

127.0.0.1 localhost

Add a unique alias to the line, such as link-host:

127.0.0.1    localhost link-host

Configure your tests to point at link-host. For example, if your app runs on http://localhost:8080, update your test to point to http://link-host:8080 after setting up the alias.

If you run the Link Agent inside a Docker or Podman container, including a Docker Compose service or a container in Windows WSL2, localhost inside the container refers to the container's own loopback network, not the host machine. A test pointed at localhost reaches the container rather than the service on your host, and the connection fails.

To reach a service bound to localhost on the host machine, either:

  • Run the container with host networking (--network host or --net=host) so it shares the host's network, or
  • Run the Link Agent directly on the host instead of in a container.

For example, to start the Link Agent with host networking:

$ docker run --net="host" mablhq/link-agent:latest --api-key {your-api-key} --name {tunnel-name}

On an arm64 host, such as an Apple silicon Mac, use mablhq/link-agent:latest-ubuntu instead. See Link with Docker.

Update the following placeholders:

  • {your-api-key}: your "Link Agent" API key from Settings > APIs in the mabl app.
  • {tunnel-name}: the tunnel name, 1 to 24 characters of lowercase letters, numbers, and dashes.

IPv4 and IPv6

A service might listen on only one of IPv4 (127.0.0.1) or IPv6 ([::1]). When a test goes to a host name that resolves to a loopback address, such as localhost, and the service refuses the connection on one address family, the Link Agent tries the other, so the service is reached either way.

A test that uses a literal address, such as http://127.0.0.1:3000, connects only to that address. If your service listens only on IPv6, point the test at localhost instead, or bind the service to both 127.0.0.1 and [::1].

Learn more

Related articles