Turn your manual testers into automation experts!Request a Demo

Dokku Testing: How to Test Your App’s Nginx Routing with testRigor

Weekly Newsletter
Receive weekly testRigor newsletters packed with insights on test automation, codeless testing, and the latest advancements in AI.
Dokku deployment architecture showing nginx routing application traffic

Dokku testing helps verify that an application still works through its public URLs after deployment or configuration changes. Dokku is an open-source platform for deploying and managing applications on your own server. It handles builds, containers, processes, and application routing, but a successful deployment does not guarantee that every request reaches the correct service.

Imagine a dashboard that loads normally while its API requests reach the wrong process. Or a chat interface that opens but cannot establish a WebSocket connection. An application redirect might also send users to a path that the proxy does not recognize. These are the kinds of problems browser-based regression tests should catch before they affect users.

This guide focuses on testing nginx path-based routing to non-web processes with testRigor. It uses a real eight-case browser suite as a practical example, while explaining how to adapt the approach to an application you deploy with Dokku.

Version note: Dokku documents the proxy:route:* commands for version 0.39.0. The example in this article was tested against a development source revision and may not work with older Dokku releases. Check your installed version and the routing documentation before using these commands.

What Should Dokku Testing Cover for Nginx Routing?

A Dokku application can have a web process for the main website, an api process for HTTP endpoints, and another process for WebSocket traffic. The important question is not simply whether those processes are running. It is whether a user request reaches the intended process and produces the expected result.

A useful regression suite should check the following journeys:

These checks protect more than a configuration file. They help establish that browsers can use the application after deployments, routing changes, and process lifecycle events.

How Dokku Routes Requests to Your Application

By default, the nginx proxy sends application traffic to the web process. Dokku’s path-based routing feature lets you direct a selected URL prefix to a different process within the same application. Other requests still use the web catch-all.

The example testing fixture defines three processes:

Its Procfile contains:
web: python server.py web
api: python server.py api
ws: python ws.py

The fixture serves the main page on port 5000, an API on port 5001, and a WebSocket server on port 5002. Once those processes are deployed, Dokku can route /api/v0 and /ws to their respective upstreams.

In the dedicated browser-probe test application, the setup uses these commands:
dokku ps:scale browser-probe web=1 api=1 ws=1
dokku proxy:route:set browser-probe api /api/v0 --port 5001
dokku proxy:route:set browser-probe ws /ws --port 5002
dokku proxy:route:report browser-probe

For your own app, replace the application name, process names, prefixes, and ports with those you actually deploy. Dokku can also strip a matching prefix before forwarding the request with --strip-prefix. That behavior matters when a backend expects /login but the public URL is /api/v0/login.

See the official proxy route reference for matching rules, port options, and backend-specific behavior.

What Dokku Already Tests, and Why Browser Tests Still Matter

Dokku has native tests for routing. For example, tests/unit/proxy-route-nginx.bats checks route selection, prefix stripping, route removal, and WebSocket upgrade directives in generated nginx configuration.

Those tests are valuable. They exercise the behavior of Dokku’s routing implementation and catch regressions without requiring a cloud browser service. However, finding an upgrade header in generated nginx configuration does not, by itself, prove that a browser can open a WebSocket and exchange a message with the deployed service.

Similarly, a correctly rendered route does not establish that a page’s JavaScript fetch reaches the correct backend, or that a browser follows an application redirect to the intended destination. A practical Dokku testing strategy adds browser evidence at that boundary without replacing the native tests.

Unit Testing in Dokku

Unit tests target individual pieces of behavior, such as parsing and validating route definitions. They give maintainers fast feedback about a particular rule or function. For application developers, the equivalent layer covers their own routing helpers, URL generation, and application logic.

Integration Testing in Dokku

Integration tests examine whether components cooperate. In this scenario, important boundaries include Dokku’s route commands, nginx configuration generation, process containers, and upstream responses. A command can succeed while the browser still reaches an unexpected endpoint, so integration checks and end-to-end checks answer different questions.

End-to-End Dokku Testing

End-to-end testing starts from the user-facing URL and follows an entire interaction through the proxy and the application. For the WebSocket case, that journey is:

Open the application → enter a message → send it over WebSocket → receive the echo → verify the expected backend and Host header.

The browser has to execute JavaScript, establish the connection, receive the server’s response, and show the result. That is a different level of evidence from checking nginx configuration alone.

Tools for End-to-End Dokku Testing

testRigor

testRigor lets teams describe browser interactions and assertions in plain English. For Dokku routing, that means a test can click a button, verify text rendered after an API call, or check the result of a WebSocket exchange without expressing each action as a CSS selector or custom browser script.

The eight-case example also uses the testRigor CLI to run Chrome tests against a local Dokku instance through a localhost tunnel. This is useful for temporary development environments that are not publicly reachable.

Selenium

Selenium is an open-source browser automation ecosystem with bindings for several programming languages. It offers flexibility for engineering teams that want to write and maintain their tests in code. Checking JavaScript-rendered output is straightforward, while more specialized network behavior may require application-side instrumentation or additional tooling.

Playwright

Playwright provides code-driven browser automation, locators, tracing, and request inspection. It is a good fit for teams already maintaining JavaScript or TypeScript test suites. testRigor offers an alternative when the team prefers readable, browser-level test steps and cloud execution. None of these tools replaces Dokku’s own command and integration tests.

Dokku Testing with testRigor: A Practical Browser Walkthrough

We will use the application from the Dokku routing browser-test contribution. Its small test page is deliberately simple: one button fetches the API’s identity, and another sends a message through a WebSocket. The response appears in the browser, where testRigor can validate it.

Use an isolated environment. The broader example changes process scale, application configuration, and routes. Do not run those destructive lifecycle checks against a production application serving users. A regular staging deployment is enough to start; the example repository harness uses a more elaborate isolated Docker setup for reproducible testing.

Step 1: Prepare the Application and Test Environment

In your own Dokku deployment, verify that the application is reachable through a staging hostname and that the test routes point to the intended processes. The example fixture instead publishes http://localhost:19080 on loopback and uses the CLI tunnel to give the remote browser access.

Before writing browser checks, confirm the route declarations and nginx configuration:
dokku proxy:route:report browser-probe
dokku nginx:validate-config browser-probe

These commands are useful setup checks, but they do not replace the browser assertions below. If you are using the example harness, let its installer create and verify the fixture instead of pointing the tests at an unrelated Dokku app.

Step 2: Create a Dokku Testing Suite in testRigor

To test a publicly reachable staging app through the testRigor web interface:

  1. Sign in to testRigor and create a new test suite.
  2. Choose a desktop Chrome testing profile and give the suite a descriptive name, such as Dokku Routing Regression.
  3. Enter the URL of your staging application and configure any required authentication.
  4. Create the suite, then choose Add Test Case to enter the steps manually.
Dokku testing suite creation form for desktop Chrome

For the source-controlled local example, create a dedicated private Desktop Web Chrome suite and use its ID with the CLI. The harness uploads one selected case per execution, supplies its test data, and opens the local app through the tunnel. Do not use the public example suite as a shared writable test environment.

Step 3: Configure Test Data

Good routing assertions need evidence that the correct upstream responded. The example API returns an identity marker and container hostname. The controller obtains the expected values from the fixture state, then supplies them to testRigor automatically.

Test Data key What it verifies
expectedBackendMarker The API response came from the expected configured backend.
previousHostname A restarted route no longer displays the previous container hostname.
previousBackendMarker A configuration update replaced the old marker.
expectedErrorHeading and expectedErrorDetail The correct Dokku error-page content appears when the API has no running upstream.

For your own app, use a stable, test-specific response value such as an environment marker or build revision. Do not rely only on the presence of a page heading: the heading might render even if an API call fails. The provided harness requires no manual Test Data entries because its controller writes them for each run.

Step 4: Check That the Browser Reaches the Correct Backend

On the fixture’s main page, Check backend runs browser JavaScript that fetches /api/v0/identity. The API returns its role, marker, and hostname. The page then displays the marker and container identity.

The verified TC-01 browser case uses just two commands:
click "Check backend"
check that page contains stored value from "expectedBackendMarker"

This part of Dokku testing checks the result rendered by the browser, not merely the HTTP status of the original page. The fixture additionally rejects responses whose role is not api. A separate HTTP check in the controller confirms the expected role and marker after the browser verdict.

Dokku testing verifies the API backend marker after a browser fetch

Step 5: Test a Real WebSocket Exchange

WebSocket routing deserves its own test. A page can load and an nginx config can include upgrade headers while a live connection still fails. In the fixture, clicking Send WebSocket message opens a connection to /ws. The server responds with the message, configured backend marker, and request Host header.

The test generates a unique value, sends it, and checks that the browser shows the exact value returned. In this particular example, generate unique email simply creates a unique message payload; the scenario is not testing email delivery.

Complete WebSocket Test Case

This is the actual plain-English content of TC-06:
generate unique email, then enter into "Message" and save as "sentMessage"
click "Send WebSocket message"
check that page contains string with parameters "Echo: ${sentMessage} Marker: ${expectedBackendMarker}"
check that page contains "HTTP Host: localhost:19080"
check that page contains "WebSocket Host: localhost:19080"

The final two checks are specific to the loopback fixture. When adapting the case to a staging domain, replace them with the Host value your environment should preserve. The controller also performs an independent WebSocket exchange to cross-check the browser result.

WebSocket echo shows the message, backend marker and Host header

Step 6: Validate Routing After Changes

Routing problems can appear only after a change. That is why Dokku testing should include process and route lifecycle cases, not just initial connectivity. The example prepares different fixture states before each browser case. This preparation occurs outside the plain-English test, so the browser case can stay focused on the user-visible result.

For example, TC-02 checks that an API restart changes the container while the route continues to work:
click "Check backend"
check that page contains stored value from "expectedBackendMarker"
check that page does not contain stored value from "previousHostname"
API marker and container hostname after process restart

TC-03 checks that a changed application marker replaces the old value. TC-04 removes the route and expects the web process’s 404 response, while TC-05 re-adds it and checks that the API marker returns. A general page-load test would miss these differences.

Browser displays HTTP 404 after removal of the API route

A pass after restart does not prove continuous availability during the restart. To establish an uninterrupted service-level objective, add monitoring or time-series probes that observe the entire transition.

Step 7: Check Missing Upstreams and Redirects

TC-07 scales the API process to zero. The browser follows Open routed page and checks the expected Dokku error heading and detail. The independent HTTP probe confirms a 502 response. This distinguishes a missing upstream from the intentional 404 expected when a route has been removed.

Dokku testing captures the error page when the API is scaled to zero
TC-08 tests an application-generated redirect:
click "Open API login"
check that page contains "API login page"

Here, nginx removes /api/v0 before forwarding the request, but the API knows its external prefix and redirects to /api/v0/login. The browser then reaches the login page. This does not demonstrate that Dokku automatically rewrites an application’s Location header. If your app runs under a prefix, configure its public base path accordingly, or implement an appropriate proxy response rewrite where supported and intentionally configured.

Dokku testing confirms the prefix-aware redirect to the API login page

Eight Verified Dokku Testing Scenarios for Nginx Routing

The following cases come from the source-controlled suite. Each link opens an execution published by the example GitHub Actions workflow on November 18, 2026.

Case Browser-visible behavior Example execution
TC-01 API identity is rendered after a browser fetch. View execution
TC-02 Route works after restart; previous hostname is absent. View execution
TC-03 New configuration marker appears instead of the old one. View execution
TC-04 Removed route falls back to the web process and shows a 404. View execution
TC-05 Restored route reaches the API again. View execution
TC-06 Live WebSocket echo, backend marker, and Host are displayed. View execution
TC-07 Scaled-zero API displays Dokku’s error page. View execution
TC-08 Prefix-aware redirect reaches the API login page. View execution

The workflow completed successfully at source revision 4b6d58af3. Its reports identify all eight browser cases as passed, with matching independent HTTP or WebSocket checks and verified cleanup.

You can also open the public example suite. The contribution was proposed in PR #9299, which was closed without being merged into the upstream Dokku repository. These results show a successful example run, not part of Dokku’s official CI.

Dokku Testing Tips for Reliable Automation

The real test fixture illustrates several useful practices:

  • Assert the backend, not only the page. A response marker and process identity help distinguish a correct upstream from a fallback page that also returned HTTP 200.
  • Use independent expected values. Obtain the expected marker from controlled configuration and a prior hostname from the running container, rather than trusting the response under test to tell you what was expected.
  • Distinguish route removal from process unavailability. In this fixture, removal results in a web-process 404; scaling the routed API to zero results in a Dokku error page with HTTP 502.
  • Test application-aware prefixes. Stripping a request prefix does not automatically fix redirects generated by an application that assumes it lives at the root URL.
  • Keep destructive state changes outside browser test steps. Prepare routes and scale through a controlled harness, then restore the original state even if the browser assertion fails.
  • Do not let an HTTP probe replace the browser result. The example runs both. A mismatch fails its controller rather than silently accepting whichever result is more convenient.
  • Adapt Host expectations to the environment. localhost:19080 is meaningful for the provided fixture, not for a public staging hostname.

When to Run Your Dokku Testing Suite

Run a small browser smoke test after an application deployment or reverse-proxy change. Expand the checks when you update API behavior, redirect paths, WebSocket endpoints, process scaling, or environment configuration. For critical paths, a scheduled regression run can catch changes outside your release process.

Not every check needs to run on every commit. Browser identity and API access checks are relatively small. Tests that restart a process, remove a route, or scale an upstream to zero should use an isolated environment and may belong in a separate regression job.

For Developers: Reproducing the Source-Controlled Test Suite

You do not need to build Dokku from source to test an existing staging application with testRigor. The following instructions are for developers who want to reproduce the exact demonstration behind the eight published executions.

The upstream PR was not merged, but its tested commit remains available from the Dokku repository through the pull request reference. The harness requires x86-64 Linux, Bash, Docker Engine with Compose, privileged Docker support, Python 3, Git, Node.js matching tests/E2E/.node-version, and testRigor credentials. It builds Dokku from committed source and creates the browser-probe app inside a separate Docker daemon.

Start from the tested revision and install the locked CLI dependency:
git clone https://github.com/dokku/dokku.git
cd dokku
git fetch origin pull/9299/head
git switch -c dokku-routing-e2e-demo 4b6d58af3c65cefe955a01146535fdd453227179
npm ci --prefix tests/E2E
Create your own dedicated suite, then supply its ID and API token securely:
export TESTRIGOR_SUITE_ID="YOUR_PRIVATE_SUITE_ID"
read -rsp "testRigor API token: " TESTRIGOR_API_KEY; echo
export TESTRIGOR_API_KEY
export DOKKU_SOURCE_REVISION=$(git rev-parse HEAD)
export DOKKU_E2E_IMAGE=dokku-e2e/source:${DOKKU_SOURCE_REVISION:0:9}
export DOKKU_HARNESS_BRANCH=$(git branch --show-current)
export E2E_ARTIFACTS=$(mktemp -d)
Build the isolated environment, install the fixture, execute the cases, and generate the report:
bash tests/E2E/scripts/build-dokku.sh "$E2E_ARTIFACTS"
bash tests/E2E/scripts/install-dokku.sh install
python3 tests/E2E/scripts/run-ci.py "$E2E_ARTIFACTS/positive"
python3 tests/E2E/scripts/report-results.py "$E2E_ARTIFACTS/positive"
Stop the test environment afterward:
docker compose -f tests/E2E/compose.yml down --remove-orphans
unset TESTRIGOR_API_KEY

For a focused run, the controller accepts --cases 6 to select the WebSocket case. It also has separate negative controls that deliberately produce incorrect fixture states to verify that the browser assertions fail for the intended reason. Those controls are development checks, not normal successful routing scenarios.

The example README documents the full setup, and COVERAGE.md explains the eight assertions and their overlap with the native tests. Its optional GitHub Actions workflow uses a repository variable named TESTRIGOR_SUITE_ID and a secret named TESTRIGOR_CI_TOKEN, skips unconfigured or fork-PR runs, and publishes reports for completed executions.

Additional Resources

Conclusion

A Dokku deployment can be healthy while an important user journey is not. Routes can target the wrong process, restart or configuration changes can expose stale behavior, WebSocket upgrades can fail, and redirects can send users outside the intended prefix.

The most useful Dokku testing strategy therefore combines native routing tests with a few checks that exercise the application through its real browser entry point. Start by checking the rendered API identity, add a live WebSocket interaction if your app uses one, and then cover the lifecycle or failure cases that matter to your deployment. Keep disruptive tests in an isolated environment and use the execution reports to investigate what users would actually experience.

You're 15 Minutes Away From Automated Test Maintenance and Fewer Bugs in Production
Simply fill out your information and create your first test suite in seconds, with AI to help you do it easily and quickly.
Achieve More Than 90% Test Automation
Step by Step Walkthroughs and Help
14 Day Free Trial, Cancel Anytime
“We spent so much time on maintenance when using Selenium, and we spend nearly zero time with maintenance using testRigor.”
Keith Powe VP Of Engineering - IDT
Privacy Overview
This site utilizes cookies to enhance your browsing experience. Among these, essential cookies are stored on your browser as they are necessary for ...
Read more
Strictly Necessary CookiesAlways Enabled
Essential cookies are crucial for the proper functioning and security of the website.
Non-NecessaryEnabled
Cookies that are not essential for the website's functionality but are employed to gather additional data. You can choose to opt out by using this toggle switch. These cookies gather data for analytics and performance tracking purposes.