Dev Container CLI

You can provide extra files (like a Dockerfile or lifecycle scripts) for a specific scenario by creating a directory named after the scenario inside test/<FEATURE>/. The contents of this directory are copied into the hidden .devcontainer folder used during the build.

Example Structure: If you have a scenario named frowning_with_a_dockerfile:

└── test
    └── smile
        ├── frowning_with_a_dockerfile  <-- Folder name matches scenario
        │   └── Dockerfile              <-- Copied to .devcontainer/
        └── frowning_with_a_dockerfile.sh

You can install the CLI using a standalone script that downloads a bundled Node.js runtime. This method does not require a pre-installed Node.js environment. It is supported on Linux and macOS (x64 and arm64).

To install, run the curl script and then add the installation directory to your PATH.

To use the Dev Container CLI, you must first install Node.js and its build dependencies.

Prerequisites:

1. Node.js 16+: Install via a manager like nvm.
2. node-gyp dependencies:
   • Linux/WSL2: sudo apt-get update && sudo apt-get install python3-minimal gcc g++ make (on Ubuntu/Debian).
   • macOS: Install XCode Command Line Tools.
3. OpenSSH: Ensure an OpenSSH compliant ssh command is in your PATH (required for SSH-based examples).

Installation Command: Install the latest version globally using npm:

npm install -g @devcontainers/cli

Duplicate-style tests verify that a Feature can be installed multiple times with different options without causing conflicts. If a Feature contains a duplicate.sh script, the CLI will automatically generate a test case installing that Feature twice.

During these tests, the options used for the distinct installations are passed into the duplicate.sh script as environment variables. For example, if a Feature has a version option, the script can access ${VERSION} (for the randomized installation) and ${VERSION__DEFAULT} (for the default installation).

The CLI is written in TypeScript and uses esbuild for bundling. You can build the project using the following commands:

Incremental Builds (Watch Mode)

Run these in separate terminals to automatically rebuild on file changes:

npm run watch            # incremental esbuild (rebuilds on save)
npm run type-check-watch # tsc in watch mode (reports type errors)

One-shot Builds

• Compile: npm run compile (builds the project once).
• Clean: npm run clean (removes all build output).

VS Code Integration

Use the default build task (Ctrl+Shift+B / Cmd+Shift+B) to run npm run watch and npm run type-check-watch in parallel.

If you wish to build the CLI from the repository source, use yarn to compile the project.

yarn
yarn compile

# Verify the build
node devcontainer.js --help

To install the CLI as an npm package, use the @devcontainers/cli package. Note that you must have Python and C/C++ installed on your system to build required dependencies.

npm install -g @devcontainers/cli

The test command provides a built-in testing framework for iterating on self-authored Features. It utilizes the CLI's build and exec commands to test Features within your local source tree.

By default, the command looks for a src directory containing Feature source code and a test directory containing assertion scripts. For a Feature named <FEATURE>, it auto-generates a test and executes test/<FEATURE>/test.sh inside the container. A test passes if the container builds successfully and the script exits with code 0.

To run tests for a specific feature (e.g., dotnet) with a specific base image, use:

devcontainer features test -f dotnet --base-image ubuntu

Tests use Mocha and Chai and require Docker. Crucially, you must package the CLI into a tarball before running tests, as the test suite installs the CLI from a .tgz file and executes it as a subprocess.

Test Workflow

1. Package the CLI:

npm run package

Note: You must re-run this command after any code change so the tarball reflects your latest changes.

2. Execute Tests:

npm test                          # all tests
npm run test-container-features   # Features tests only
npm run test-container-templates  # Templates tests only

Adding New Tests

• Place new test files in src/test/ with a .test.ts suffix.
• Place test fixture devcontainer.json configurations under src/test/configs/<your-config-name>/.
• Use helpers in src/test/testUtils.ts (e.g., shellExec, devContainerUp, devContainerDown) for container lifecycle management.

The CLI generates .devcontainer-lock.json files by default during build or up operations to pin feature versions for reproducible builds. You can control this behavior using the following flags:

• --no-lockfile: Opt out of generating/using a lockfile.
• --frozen-lockfile: Enforce the use of an existing lockfile.

Scenarios allow you to test complex configurations, such as multiple Features in one container or specific Feature options. A scenario is defined as a JSON object where the key is the scenario name and the value is a devcontainer.json configuration snippet.

When a scenario is defined, the CLI looks for a shell script named <scenario_name>.sh in the test/<FEATURE>/ directory to execute the assertions.

Example test/oryx/scenarios.json:

{
    "install_dotnet_and_oryx": {
        "image": "ubuntu:focal",
        "features": {
            "dotnet": {
                "version": "6",
                "installUsingApt": "false"
            },
            "oryx": {}
        }
    }
}

In this example, the CLI will execute test/oryx/install_dotnet_and_oryx.sh inside the container.