Testing is a crucial part of any website’s development process.
One excellent tool for automating tests on websites is Playwright, which provides a robust framework for end-to-end testing.
Integrating Playwright with Hugo allows developers to test various aspects of the site across multiple browsers and devices, ensuring that the website behaves as expected.
Prerequisites
Node.js: Ensure you have Node.js installed, as Playwright runs on Node.
Environment File: For flexible configuration, set up a .env file with a variable BASE_URL_TESTING, which specifies the URL of your site for testing.
Setting up playwright.config.js
The playwright.config.js file is where you configure test directories, base URLs, and browser settings.
Create / update the playwright.config.js in your main directory.
// @ts-check
const{defineConfig,devices}=require('@playwright/test');importdotenvfrom'dotenv';importpathfrom'path';// Read from ".env" file.
dotenv.config({path:path.resolve(__dirname,'.env')});// Use the environment variable for the base URL
constbaseURL=process.env.BASE_URL_TESTING||'http://localhost:1313';/**
* @see https://playwright.dev/docs/test-configuration
*/module.exports=defineConfig({testDir:'./tests',fullyParallel:true,forbidOnly:!!process.env.CI,retries:process.env.CI?2:0,workers:process.env.CI?1:undefined,reporter:'html',use:{baseURL,trace:'on-first-retry',},projects:[{name:'chromium',use:{...devices['Desktop Chrome']},},{name:'firefox',use:{...devices['Desktop Firefox']},},{name:'webkit',use:{...devices['Desktop Safari']},},{name:'Microsoft Edge',use:{...devices['Desktop Edge'],channel:'msedge'},},],webServer:{ignoreHTTPSErrors:true,command:'npm run start',url:baseURL,reuseExistingServer:process.env.REUSE_SERVER==='true',}});
...
baseURL: Dynamically set the base URL from the .env file. This allows for testing different environments by simply changing the environment variable. Default: http://localhost:1313
Projects: Defines multiple browser configurations (Chrome, Firefox, Safari, and Edge), enabling tests to run across various browsers.
Retries and Workers: Customizes retries and workers for CI environments to enhance reliability and performance.
This setup provides flexibility, enabling you to test the website across multiple browsers while keeping configuration changes manageable.
Define tests in the tests folder of your hugo repository.
Example Test: showCustom404.spec.js
Testing for custom error pages (like a 404 page) is essential, as it ensures users get a user-friendly response when navigating to a non-existent page.
import{test,expect}from'@playwright/test';test('showCustom404',async({page})=>{// Go to a non-existent page
awaitpage.goto('/en/fdaffa');// Check for a custom 404 element
constelement=awaitpage.$('#fa-face-frown');expect(element).not.toBeNull();// Go to the homepage and check the absence of the 404 element
awaitpage.goto('/');consthomeElement=awaitpage.$('#fa-face-frown');expect(homeElement).toBeNull();});
...
Explanation of showCustom404.spec.js
Navigating to a Non-existent Page: The test navigates to a non-existent URL (/en/fdaffa), where we expect to see the custom 404 page.
Checking for the 404 Indicator: The code looks for an element with the ID #fa-face-frown, which signifies that the 404 page has loaded. If this element is found, the test passes this check.
Verifying normal page behavior: The test then navigates back to the homepage (/). Here, it verifies that the 404 indicator is absent, confirming that the 404 component does not mistakenly appear on valid pages.
Running the Tests
To execute the tests, simply use the following command. Run local the Hugo Server before running the tests.
1
npx playwright test
This command runs all tests in the tests directory.
If you want to run the test with a running Hugo server use:
REUSE_SERVER=true
in your .env file.
The HTML reporter specified in the configuration (reporter: ‘html’,) will generate a detailed report in a browser, which helps in visualizing and debugging test results. Default dictionary: playwright-report
Playwright automatically creates a .gitignore file to exclude unnecessary files from being tracked in your repository.
Ensure for:
/test-results/
/playwright-report/
/blob-report/
/playwright/.cache/
GitHub action
Define under in your github repo under /settings/variables/actions the repository variable:
name:🧪 Playwright End To End (e2e) Tests Workflowon:# Runs on pushes targeting the default branchpush:branches:- main# Allows you to run this workflow manually from the Actions tabworkflow_dispatch:jobs:tests_e2e:name:Run end-to-end tests for live websiteruns-on:ubuntu-latestenv:BASE_URL_TESTING:${{ vars.BASE_URL_TESTING }}REUSE_SERVER:'true'steps:- uses:actions/checkout@v3- uses:actions/setup-node@v3- name:Install dependenciesrun:npm ci- name:Install playwright browsersrun:npx playwright install --with-deps- name:Run testsrun:npx playwright test
...
Jest
I was trying to use Jest with Hugo but was not satisfied with the results. The current setup with Hugo is the easiest way for me at the moment.
Generate a starting point for all websites pages
As a starting point you could automatically generate a few test cases. I was testing this with the Mistral API and use the sitemap.xml to generate a test case for all pages.
Requirements: Get the free Mistral API, create a .env in the .py file directory
.env file
1
MISTRAL_API_KEY=your_api_key
.py file
1
2
# Fetch sitemap from URLsitemap_url="https://d-oit.github.io/en/sitemap.xml"