Registry / testing / codeceptjs-postgresqlhelper

codeceptjs-postgresqlhelper

JSON →
library1.0.1jsnpmunverified

CodeceptJS helper (version 1.0.1) designed to streamline end-to-end testing against PostgreSQL databases. This package allows developers to execute raw SQL queries directly from their CodeceptJS test scenarios, which is crucial for setting up test data, verifying database states, and cleaning up after tests. It integrates into the CodeceptJS ecosystem by being configured in `codecept.conf.js` and exposing its methods via the framework's actor object (`I`). This helper differentiates itself from general PostgreSQL client libraries by providing a test-centric interface within the CodeceptJS testing paradigm. The project is maintained by Percona-Lab, with its release cadence currently driven by community contributions and specific project needs.

npm install codeceptjs-postgresqlhelper
INSTALL
IMPORT
SIG · CODECEPTJS-POSTGRE
C
codeceptjs-postgresqlhelper
testingjavascriptv1.0.1
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

PostgresqlDBHelper Class
✓ const PostgresqlDBHelper = require('codeceptjs-postgresqlhelper');
This is how the raw helper class module is directly imported, typically for advanced custom extensions or debugging, rather than direct use in test files.
Configuration `require`
✓ helpers: { PostgresqlDBHelper: { require: 'codeceptjs-postgresqlhelper', // ... configuration options } }
✗ import { PostgresqlDBHelper } from 'codeceptjs-postgresqlhelper';
The primary way developers 'import' this package is by referencing it in the `helpers` section of `codecept.conf.js`. CodeceptJS uses Node.js `require` internally for loading helpers, and this package does not provide ESM exports.
I.runQuery (in tests)
✓ await I.runQuery('SELECT * FROM my_table;');
After the helper is configured, its methods, such as `runQuery`, become available directly on the CodeceptJS actor object `I` within test scenarios. This is the most common way to interact with the helper in tests.

This quickstart demonstrates how to configure the `PostgresqlDBHelper` in a `codecept.conf.js` file, utilizing environment variables for secure credential management. It then provides an example CodeceptJS scenario (`my_db_test.js`) that uses the `I.runQuery` method to perform a full database test lifecycle: creating a temporary table, inserting test data, verifying the insertion, and finally cleaning up the table, ensuring isolated tests.

const { setHeadlessWhen, setWindowSize } = require('@codeceptjs/configure'); setHeadlessWhen(process.env.CI); setWindowSize(1200, 800); exports.config = { tests: './*_test.js', output: './output', helpers: { PostgresqlDBHelper: { require: 'codeceptjs-postgresqlhelper', host: process.env.DB_HOST ?? '127.0.0.1', port: parseInt(process.env.DB_PORT ?? '5432'), user: process.env.DB_USER ?? 'postgres', password: process.env.DB_PASSWORD ?? 'postgres', database: process.env.DB_DATABASE ?? 'testdb', }, // Include another helper if browser interaction is needed, e.g., Playwright // Playwright: { // url: 'http://localhost', // show: true, // browser: 'chromium' // } }, include: {}, bootstrap: async () => { // Optional: run initial setup like creating the database if it doesn't exist // (requires a separate connection for initial DB creation) }, teardown: null, mocha: {}, name: 'codeceptjs-postgresqlhelper-quickstart', plugins: { retryFailedStep: { enabled: true }, screenshotOnFail: { enabled: true } } }; // --- my_db_test.js --- Feature('Database Operations'); Scenario('should create a table, insert data, and verify', async ({ I }) => { const tableName = 'test_users_' + Date.now(); const username = 'john_doe_' + Date.now(); const email = username + '@example.com'; // 1. Create a table await I.runQuery(`CREATE TABLE IF NOT EXISTS ${tableName} (id SERIAL PRIMARY KEY, username VARCHAR(255) UNIQUE, email VARCHAR(255));`); console.log(`Table ${tableName} created or already exists.`); // 2. Insert data await I.runQuery(`INSERT INTO ${tableName} (username, email) VALUES ('${username}', '${email}');`); console.log(`Inserted user ${username}.`); // 3. Verify data insertion const selectResult = await I.runQuery(`SELECT * FROM ${tableName} WHERE username = '${username}';`); I.assert(selectResult.rows.length).equals(1); I.assert(selectResult.rows[0].email).equals(email); console.log(`Verified user ${username} in table.`); // 4. Clean up (optional, but good practice for isolated tests) await I.runQuery(`DROP TABLE ${tableName};`); console.log(`Table ${tableName} dropped.`); });
Debug
Known issues
gotchaDirectly embedding sensitive database credentials (host, port, user, password, database) into `codecept.conf.js` is a security risk. These values should be externalized, especially in shared or CI/CD environments.
fix
Use environment variables (e.g., `process.env.DB_HOST`) to pass credentials to the helper configuration. Tools like `dotenv` can assist with local development environment variables.
affects: >=1.0.0
gotchaConstructing SQL queries by directly concatenating unsanitized string inputs (e.g., from user input or external sources) can lead to SQL injection vulnerabilities.
fix
For dynamic values, ensure all inputs are properly sanitized or, if the underlying `pg` client were directly exposed, use parameterized queries. For test data originating from trusted scripts, this risk is reduced but still a good practice to be aware of.
affects: >=1.0.0
breakingThis package is a CodeceptJS helper and is designed to run within the CodeceptJS framework. It cannot be used as a standalone Node.js PostgreSQL client library.
fix
If standalone PostgreSQL interaction is needed outside CodeceptJS tests, use the `pg` package directly or another dedicated PostgreSQL client library.
affects: >=1.0.0
gotchaEnsure your PostgreSQL database server is running and accessible from where CodeceptJS tests are executed. Network firewalls or incorrect host/port configurations can prevent connections.
fix
Verify the PostgreSQL service status, check firewall rules, and confirm `host` and `port` settings in `codecept.conf.js` match your database server configuration.
affects: >=1.0.0
Errors
Common errors & fixes
Error: connect ECONNREFUSED 127.0.0.1:5432
The CodeceptJS helper could not establish a connection to the PostgreSQL server at the specified host and port.
fix
Verify that the PostgreSQL server is running, listening on the specified port (`5432` by default), and accessible from the machine running CodeceptJS tests. Check firewall rules if applicable. Confirm `host` and `port` in `codecept.conf.js`.
Error: password authentication failed for user "postgres"
The provided username or password in the helper configuration is incorrect for the PostgreSQL database.
fix
Double-check the `user` and `password` values in `codecept.conf.js` against your PostgreSQL user credentials. Ensure the user has permissions to connect to the specified database.
Error: database "testdb" does not exist
The specified database name in the helper configuration does not exist on the PostgreSQL server.
fix
Ensure the `database` name in `codecept.conf.js` matches an existing database on your PostgreSQL server, or create the database if it's missing.
Upgrade
Version history
1.0.1latest on npm
Audit
Dependencies
pgrequiredRuntime dependency for establishing and managing connections to PostgreSQL databases.
@codeceptjs/helperrequiredPeer dependency as it extends the base CodeceptJS helper class.
Agent activity
13 hits · last 30 days
node
12
OpenAI (training)
1
Resources
codeceptjs-postgresqlhelper — npm install codeceptjs-postgresqlhelper · libregistry