@oxctl/deployment-test-utils

Shared configuration and utility scripts to support Canvas LTI tool deployment (E2E) tests with Playwright.

This package provides:

• A pre-test authentication CLI (deployment-generate-auth)
• A shared Playwright config
• A small set of test utilities (helpers for logging in, handling banners, waiting for spinners, etc.)

Authentication is performed outside of Playwright tests and persisted via storageState, avoiding token leakage in reports.

Installation

In your consumer project (the project in which you want to run deployment tests):

npm i -D @oxctl/deployment-test-utils

Configuration

Add the required dev dependencies to your project (use your preferred package manager and versions):

npm i -D @oxctl/deployment-test-utils @playwright/test dotenv

Optionally install Playwright browser binaries (if you haven't already):

npx playwright install

This library does not pin a Node.js version. Use a version appropriate for your project. Requires @playwright/test >= 1.60.0 due to a browser install hang affecting older Playwright versions on Node 24.16+.

Environment variables

The following must be set (locally via .env, or in CI via your provider's secrets/variables):

• CANVAS_HOST - trailing slash is optional
• OAUTH_TOKEN
• TEST_PATH - leading slash is optional

Example:

CANVAS_HOST=https://wibble.instructure.com
OAUTH_TOKEN=12345~QWERTYUIOPASDFGHJKLZXCVBNM
TEST_PATH=/accounts/1/external_tools/789

Authentication (pre-test step)

This package exposes a CLI, deployment-generate-auth It will:

1. Validate required environment variables
2. Request a session token
3. Launch a browser and establish a session
4. Save Playwright storageState to: playwright/.auth/user.json in the consumer repo workspace

⚠️ Note: In GitHub Actions this file is only created in the ephemeral job workspace and is cleaned up automatically when the job ends. It is not committed to source control, and there is no risk of leaking long-lived credentials.

It is not tidied up on your local machine and should never be committed to source control so should be added to .gitignore.

Playwright config

import { config } from '@oxctl/deployment-test-utils'

export default config

The config:

• Loads .env
• Uses the generated storageState

Write The Tests

Write The Tests

Use the utilities from this repository when writing your deployment tests. Here's a simple example which asserts that some specific text, XXXXXXXXXXXXXXX, appears on a page. The test(s) can be as simple or as complex as seems appropriate.

import { dismissBetaBanner, getLtiIFrame, waitForNoSpinners, grantAccessIfNeeded, TEST_URL } from '@oxctl/deployment-test-utils'

test.describe('Test deployment', () => {
    test('The tool should load and the text "XXXXXXXXXXXXXXX" should be shown', async ({context, page}) => {
    await page.goto(TEST_URL)
    await dismissBetaBanner(page)
    // Handle LTI “Grant Access” flow if required
    await grantAccessIfNeeded(page, context, TEST_URL)
    const ltiIFrame = getLtiIFrame(page)
    await waitForNoSpinners(ltiIFrame)

    // Check there's specific text on the page
    const text = ltiIFrame.getByText("XXXXXXXXXXXXXXX")
    await expect(text).toBeVisible();
  })
})

If your LTI tool requires the user to grant access, you must call grantAccessIfNeeded in your tests. This is no longer handled during authentication setup.

Optional: Skip page navigation in grantAccessIfNeeded

If toolUrl is provided, grantAccessIfNeeded navigates to it. If your test has already navigated to the tool, omit toolUrl to skip the navigation step:

// Already at the tool URL
await page.goto(TEST_URL)
// Check for grant access flow without re-navigating
await grantAccessIfNeeded(page, context)

Optional: Register a cookie-dialog handler once per test

If your environment shows the OneTrust cookie dialog unpredictably, register a locator handler in test setup so it is auto-accepted whenever it appears:

import { registerCookieDialogHandler } from '@oxctl/deployment-test-utils'

test.beforeEach(async ({ page }) => {
  await registerCookieDialogHandler(page)
})

Recommended npm scripts

{
  "scripts": {
    "install-browsers": "npx playwright install --with-deps chromium",
    "pretest": "deployment-generate-auth",
    "test": "playwright test",
    "test:ci": "CI=true npm test",
    "test:ui": "npm test -- --ui",
    "test:report": "playwright show-report"
  }
}

This ensures auth always runs before tests.

Project structure

src/
├── config.js          # shared Playwright config (loads dotenv, sets `storageState`)
├── testUtils.js       # reusable Playwright helpers and `TEST_URL`
├── shared/
│   └── url.js         # pure helpers for normalising/building URLs

bin/
└── auth.setup.js      # CLI: generates authenticated `storageState`

Development

In this repo:

npm run build      # bundle testUtils.js to dist/
npm pack           # create a tarball for local install

In the consumer repo:

npm i ../path/to/oxctl-deployment-test-utils-1.0.0.tgz

Then run tests as normal:

npx playwright test

Releasing

This library is published to npmjs. To make a new release run:

npm version patch

or

npm version minor

or

npm version major

according to semver conventions.

If it completes ok, push the tags and GitHub actions will build and publish the package to npmjs:

git push
git push --tags