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 your local machine, including localhost and 127.0.0.1, without deploying it or exposing it to the internet. Use this setup to run extensive 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

The Link Agent must be running on the same machine as the service you want to test, and the environment for your test must be configured to use that Link Agent. 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 you point a cloud test at a loopback address, such as localhost or 127.0.0.1, the request routes through the Link tunnel to the machine where your Link Agent is running 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 adding an alias for localhost below for more details.

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 OSX: edit the /etc/hosts file
  • Windows: edit the C:\Windows\System32\Drivers\etc\hosts

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 --api-key {your-mabl-api-key} --name {link-agent-name}

Update the following placeholders:

  • {your-mabl-api-key}: use your Link Agent API key from Settings > APIs in the mabl app.
  • {link-agent-name}: create a name for your Link Agent between 1 and 24 characters long that consists of lowercase letters, numbers, and dashes.

If the connection still fails

The Link Agent connects to whatever address localhost resolves to on its machine, so this usually works as-is. A mismatch can occur only if the agent resolves localhost to one address family while your service listens only on the other. For example, localhost resolves to IPv4 127.0.0.1 but your service listens only on IPv6 [::1]. If you have trouble connecting, bind your service to both 127.0.0.1 and [::1], or to all interfaces (0.0.0.0).

Learn more

Related articles