On this page
testing
introduction
dframework includes a built in test harness with zero external dependencies, running directly on node's native test runner (node:test). applications can perform fast in process http requests without spinning up network sockets, test database state, and simulate browser interactions with full form and navigation fidelity in continuous integration pipelines.
the dframework/testing module exports all test runner and assertion primitives (test, describe, it, before, after, beforeEach, afterEach, and strict assert). application test files only need to import from dframework/testing without requiring any direct node:test or node:assert imports.
running tests
you can run the entire test suite or target specific files using dstrn test:
1# run all tests in tests/2dstrn test3 4# run a specific test file or directory5dstrn test tests/feature/UserTest.test.js6dstrn test tests/unit7 8# watch mode for instant re running on file changes9dstrn test --watch10 11# run only tests marked with { only: true }12dstrn test --onlydstrn test automatically sets APP_ENV=testing and enables experimental sqlite support when running under node 22 or 23. tests strictly require a .env.testing file in the project root; the framework does not fall back to .env, preventing accidental data mutations in your development or production databases.
generating tests
you can scaffold new test files using dstrn make:test:
1# create a feature test in tests/feature/2dstrn make:test UserTest3dstrn make:test UserTest --feature4 5# create a browser test in tests/browser/6dstrn make:test CheckoutTest --browser7 8# create a unit test in tests/unit/9dstrn make:test CalculatorTest --unit10 11# nested directories are created automatically12dstrn make:test Auth/RegistrationTest
http integration tests
the testApp() client provides an in process http dispatcher that passes synthetic request streams directly through the framework pipeline. this guarantees zero mock drift while avoiding live socket binding overhead.
making requests
1import { describe, it, assert, testApp } from 'dframework/testing';2 3describe('users api', () => {4 it('returns active users', async () => {5 const app = await testApp();6 const res = await app.get('/api/users');7 8 res.assertOk();9 res.assertJson({ success: true });10 });11});supported request methods include get, post, put, patch, delete, and head. cookies and session state are preserved across sequential requests within the same client instance.
you can configure custom headers, cookies, or disable automated csrf token generation:
1const app = await testApp();2 3// attach custom headers or cookies4app.withHeaders({ 'x-test-header': 'custom' });5app.withCookies({ theme: 'dark' });6 7// disable automatic csrf token generation for mutating requests8app.withoutCsrf();
named route dispatch
dispatch requests using defined route names and parameter maps:
1test('named route order lookup', async () => {2 const app = await testApp();3 const res = await app.route('orders.show', { id: 42 });4 5 res.assertOk();6 res.assertJson({ orderId: '42' });7});
direct controller execution
test controller actions or middleware chains directly using app.call():
1test('direct controller action', async () => {2 const app = await testApp();3 const res = await app.call('UserController@show', {4 uri: '/users/:id',5 params: { id: 1 }6 });7 8 res.assertOk();9});
acting as a user
use actingAs to authenticate a user before executing requests:
1test('authenticated profile view', async () => {2 const app = await testApp();3 app.actingAs({ id: 1, email: 'alice@example.com' });4 5 const res = await app.get('/profile');6 res.assertOk();7 res.assertSee('alice@example.com');8});
available assertions
the response object returned by synthetic requests provides chainable assertion helpers:
| assertion | description |
|---|---|
assertStatus(code) |
assert the response status code |
assertOk() |
assert status 200 |
assertCreated() |
assert status 201 |
assertNotFound() |
assert status 404 |
assertForbidden() |
assert status 403 |
assertUnauthorized() |
assert status 401 |
assertRedirect(uri) |
assert a redirect status and matching location |
assertJson(expected) |
assert the response json contains the expected structure or values |
assertJsonMissing(key) |
assert a key is absent from the response json |
assertSee(text) |
assert response contains the given substring |
assertDontSee(text) |
assert response does not contain the given substring |
assertHeader(name, val) |
assert response header value |
database assertions
the test harness exposes database assertion helpers directly on the test app instance:
1test('user registration records to database', async () => {2 const app = await testApp();3 4 await app.post('/register', {5 name: 'Bob',6 email: 'bob@example.com'7 });8 9 await app.assertDatabaseHas('users', { email: 'bob@example.com' });10 await app.assertDatabaseMissing('users', { email: 'charlie@example.com' });11 await app.assertDatabaseCount('users', 1);12});
migrations, seeders, and transactions
manage database state with dedicated helpers and automatically isolate test mutations using transactions:
1test('database transactions and seeding', async () => {2 const app = await testApp();3 await app.migrate();4 await app.rollback();5 await app.migrate();6 await app.seed('UserSeeder');7 8 await app.useTransaction(async () => {9 await app.post('/users', { name: 'Alice' });10 await app.assertDatabaseHas('users', { name: 'Alice' });11 });12 13 await app.assertDatabaseMissing('users', { name: 'Alice' });14});
browser and page interaction tests
the browse() client runs a lightweight simulated dom parser that executes form serialization, link traversal, input typing, checkboxes, and select dropdowns without requiring heavy headless browser binaries in continuous integration. note that simulated dom evaluates server rendered html using whitespace separated descendant selectors and :not() without running a client javascript runtime or complex combinators (such as >, +, or ~).
navigating pages
1import { describe, it, assert, browse } from 'dframework/testing';2 3describe('homepage', () => {4 it('visits and navigates via link', async () => {5 const page = await browse('/');6 7 page.assertSee('welcome to dframework');8 page.assertElement('nav');9 10 await page.click('#docs-link');11 page.assertPath('/docs');12 });13});
form interactions and clicks
1test('fill and submit contact form', async () => {2 const page = await browse('/contact');3 4 page.type('input[name="email"]', 'visitor@example.com');5 page.type('textarea[name="message"]', 'hello framework');6 page.check('input[name="newsletter"]');7 page.select('select[name="topic"]', 'support');8 9 await page.click('button[type="submit"]');10 11 page.assertPath('/contact/success');12 page.assertSee('thank you for reaching out');13});
browser assertions
| assertion | description |
|---|---|
assertPath(path) |
assert current url pathname |
assertSee(text) |
assert rendered text contains substring |
assertDontSee(text) |
assert rendered text does not contain substring |
assertElement(selector) |
assert element matching css selector exists |
assertMissing(selector) |
assert element matching css selector does not exist |
assertValue(selector, value) |
assert input or select element has expected value |
assertChecked(selector) |
assert checkbox is checked |
assertNotChecked(selector) |
assert checkbox is unchecked |

