v0.21

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 test
3
4# run a specific test file or directory
5dstrn test tests/feature/UserTest.test.js
6dstrn test tests/unit
7
8# watch mode for instant re running on file changes
9dstrn test --watch
10
11# run only tests marked with { only: true }
12dstrn test --only

dstrn 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 UserTest
3dstrn make:test UserTest --feature
4
5# create a browser test in tests/browser/
6dstrn make:test CheckoutTest --browser
7
8# create a unit test in tests/unit/
9dstrn make:test CalculatorTest --unit
10
11# nested directories are created automatically
12dstrn 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 cookies
4app.withHeaders({ 'x-test-header': 'custom' });
5app.withCookies({ theme: 'dark' });
6
7// disable automatic csrf token generation for mutating requests
8app.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 ~).

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