DEVELOPER.md
This document describes how to set up your development environment and run TypeORM test cases.
See the contribution guidelines if you'd like to contribute to TypeORM.
Before you can build and test TypeORM, you must install and configure the following products on your development machine:
Fork and clone the repository:
upstream remote pointing back to
the TypeORM repository that you forked in the first place.# Clone your GitHub repository:
git clone [email protected]:<github username>/typeorm.git
# Go to the TypeORM directory:
cd typeorm
# Add the main TypeORM repository as an upstream remote to your repository:
git remote add upstream https://github.com/typeorm/typeorm.git
You should have node installed in the version described in .nvmrc.
It is recommended to configure your OS to automatically switch to use this version whenever you enter project folder. This can be achieved in many ways:
fnmzsh-nvmasdf with asdf-nodejs plugin and legacy_version_file = true optionInstall all TypeORM dependencies by running this command:
pnpm install
To create an initial ormconfig.json file, run the following command:
cp ormconfig.sample.json ormconfig.json
To build a distribution package of TypeORM run:
pnpm run package
This command will generate a distribution package in the build/package directory.
You can link (or simply copy/paste) this directory into your project and test TypeORM there
(but make sure to keep all node_modules required by TypeORM).
To build the distribution package of TypeORM packed into a .tgz, run:
pnpm run pack
This command will generate a distribution package tar in the build directory (build/typeorm-x.x.x.tgz).
You can copy this tar into your project and run pnpm install ./typeorm-x.x.x.tgz to bundle your build of TypeORM in your project.
It is greatly appreciated if PRs that change code come with appropriate tests.
To create a new test, check the relevant functional tests. Depending on the test, you may need to create a new .test.ts file or modify an existing one.
If the test is for a specific regression or issue opened on GitHub, add a comment to the tests mentioning the issue number.
Most tests will benefit from using this template as a starting point:
import { expect } from "chai"
import "reflect-metadata"
import {
closeTestingConnections,
createTestingConnections,
reloadTestingDatabases,
} from "../../utils/test-utils"
import { DataSource } from "../../../src/data-source/DataSource"
describe("description of the functionality you're testing", () => {
let dataSources: DataSource[]
before(
async () =>
(dataSources = await createTestingConnections({
entities: [__dirname + "/entity/*{.js,.ts}"],
schemaCreate: true,
dropSchema: true,
})),
)
beforeEach(() => reloadTestingDatabases(dataSources))
after(() => closeTestingConnections(dataSources))
// optional: test fix for issue https://github.com/typeorm/typeorm/issues/<issue-number>
it("should <put a detailed description of what it should do here>", () =>
Promise.all(
dataSources.map(async (dataSource) => {
// tests go here
}),
))
// you can add additional tests if needed
})
If you place entities in ./entity/<entity-name>.ts relative to your test file,
they will automatically be loaded.
To run the tests, setup your environment configuration by copying ormconfig.sample.json into ormconfig.json and replacing parameters with your own. The tests will be run for each database that is defined in that file. If you're working on something that's not database specific and you want to speed things up, you can pick which objects in the file make sense for you to keep.
Run the tests as follows:
pnpm test
You should make sure the test suites pass before submitting a PR to GitHub. Tests are run on PRs via GitHub Actions after approval, but your fork repository should be able to run CI as well. All tests need to pass before a PR will be merged.
Executing only some tests: When you are creating tests to some specific code, you may want to only execute the tests that you're creating.
To do this, you can temporarily modify your test definitions by adding .only mocha commands to describe and it. For example:
describe.only('your describe test', ....)
Alternatively, you can use the --grep flag to pass a regex to mocha. Only the tests that have describe/it statements that match the regex will be run. For example:
pnpm run test -- --grep "your test name"
The pnpm test script works by deleting built TypeScript code, rebuilding the codebase, and then running tests. This can take a long time.
Instead, for a quicker feedback cycle, you can run pnpm run compile -- --watch to make a fresh build and instruct TypeScript to watch for changes and only compile what code you've changed.
Once TypeScript finishes compiling your changes, you can run pnpm run test:fast (instead of test), to trigger a test without causing a full recompile, which allows you to edit and check your changes much faster.
To run your tests you need the Database Management Systems (DBMS) installed on your machine. Alternatively, you can use docker with the DBMS running in containers. To have docker run all the DBMS for you simply run docker-compose up
in the root of the project. Once all images are fetched and are running, you can run the tests.
To create a new release, follow these steps:
master with the format release-x.x.x (e.g. release-0.3.23).package.json and run pnpm install to update the lockfile.pnpm run changelog to generate the changelog for the new version.master.publish-package.yml script will then run a GitHub Actions workflow that will publish the new version to npm.