Skip to content

Commit e3db1ed

Browse files
CopilotMohabMohie
Copilot
and
MohabMohie
authored
docs: add documentation for 5 low-priority undocumented SHAFT_ENGINE features (#446)
* Initial plan * Add documentation for 5 low priority items from issue #440 Agent-Logs-Url: https://github.com/ShaftHQ/shafthq.github.io/sessions/82ca3abd-264b-415a-bcf1-c5c64f530f0b Co-authored-by: MohabMohie <19201898+MohabMohie@users.noreply.github.com> * Address code review feedback: fix attach example and reorder Clipboard Actions sections Agent-Logs-Url: https://github.com/ShaftHQ/shafthq.github.io/sessions/82ca3abd-264b-415a-bcf1-c5c64f530f0b Co-authored-by: MohabMohie <19201898+MohabMohie@users.noreply.github.com> --------- Signed-off-by: Mohab Mohie <Mohab.MohieElDeen@outlook.com> Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: MohabMohie <19201898+MohabMohie@users.noreply.github.com> Co-authored-by: Mohab Mohie <Mohab.MohieElDeen@outlook.com>
1 parent ccecd69 commit e3db1ed

6 files changed

Lines changed: 1105 additions & 2 deletions

File tree

‎docs/Keywords/CLI/Docker_Terminal.md‎

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
---
2+
id: Docker_Terminal
3+
title: Docker Container Terminal
4+
sidebar_label: Docker Terminal
5+
description: "Execute commands inside running Docker containers using SHAFT Engine's TerminalActions with the Docker constructor."
6+
keywords: [SHAFT, docker terminal, container commands, CLI, TerminalActions, docker exec, automation]
7+
tags: [cli, terminal, docker, containers]
8+
---
9+
10+
SHAFT's `TerminalActions` class supports **Docker container execution** out of the box. Using the Docker-specific constructor, you can run shell commands inside any running container and capture the output — no external tooling required.
11+
12+
---
13+
14+
## Prerequisites
15+
16+
- Docker must be installed and running on the test execution machine.
17+
- The target container must already be running before `TerminalActions` is instantiated.
18+
19+
---
20+
21+
## Create a Docker Terminal
22+
23+
Pass the container name (or container ID) and the user to run commands as:
24+
25+
```java title="DockerTerminalSetup.java"
26+
import com.shaft.cli.TerminalActions;
27+
28+
// Connect to a running container named "my-app-container" as root
29+
TerminalActions docker = new TerminalActions("my-container-name", "root");
30+
```
31+
32+
You can verify that the terminal is operating inside a Docker container:
33+
34+
```java title="VerifyDockerContext.java"
35+
assertTrue(docker.isDockerizedTerminal(),
36+
"Terminal should be connected to the Docker container");
37+
```
38+
39+
---
40+
41+
## Execute Commands
42+
43+
### Single Command
44+
45+
```java title="DockerSingleCommand.java"
46+
// List files in the application directory
47+
String listing = docker.performTerminalCommand("ls -la /app");
48+
System.out.println(listing);
49+
50+
// Read a configuration file
51+
String config = docker.performTerminalCommand("cat /app/config/application.yml");
52+
53+
// Check a running process
54+
String processes = docker.performTerminalCommand("ps aux | grep java");
55+
```
56+
57+
### Multiple Commands in Sequence
58+
59+
```java title="DockerMultipleCommands.java"
60+
import java.util.List;
61+
62+
String result = docker.performTerminalCommands(
63+
List.of(
64+
"cd /app",
65+
"cat config.json",
66+
"ls logs/"
67+
)
68+
);
69+
System.out.println(result);
70+
```
71+
72+
---
73+
74+
## Common Use Cases
75+
76+
### Validate Application State Inside a Container
77+
78+
```java title="ValidateContainerState.java"
79+
import com.shaft.cli.TerminalActions;
80+
import com.shaft.driver.SHAFT;
81+
82+
@Test
83+
void verifyApplicationHealthInsideContainer() {
84+
TerminalActions docker = new TerminalActions("backend-service", "root");
85+
86+
// Check that the application process is running
87+
String processes = docker.performTerminalCommand("ps aux | grep java");
88+
SHAFT.Validations.assertThat()
89+
.object(processes)
90+
.contains("java")
91+
.withCustomReportMessage("Java process must be running inside the backend container")
92+
.perform();
93+
}
94+
```
95+
96+
### Verify a Log File
97+
98+
```java title="VerifyContainerLogs.java"
99+
TerminalActions docker = new TerminalActions("my-app", "root");
100+
101+
// Tail the last 50 lines of the application log
102+
String logs = docker.performTerminalCommand("tail -n 50 /var/log/app/application.log");
103+
104+
SHAFT.Validations.assertThat()
105+
.object(logs)
106+
.doesNotContain("ERROR")
107+
.withCustomReportMessage("No ERROR entries should appear in the last 50 log lines")
108+
.perform();
109+
```
110+
111+
### Read a Generated File from the Container
112+
113+
```java title="ReadFileFromContainer.java"
114+
TerminalActions docker = new TerminalActions("report-generator", "root");
115+
116+
// Trigger report generation inside the container
117+
docker.performTerminalCommand("./generate-report.sh");
118+
119+
// Read the generated report content
120+
String reportContent = docker.performTerminalCommand("cat /tmp/report.json");
121+
122+
// Attach to Allure report for evidence
123+
SHAFT.Report.attach("application/json", "Generated Report", reportContent);
124+
```
125+
126+
### Database Seed / Cleanup via Container
127+
128+
```java title="ContainerDatabaseOps.java"
129+
TerminalActions docker = new TerminalActions("postgres-db", "postgres");
130+
131+
@BeforeMethod
132+
void seedDatabase() {
133+
docker.performTerminalCommand("psql -U testuser -d testdb -f /scripts/seed.sql");
134+
}
135+
136+
@AfterMethod
137+
void cleanupDatabase() {
138+
docker.performTerminalCommand("psql -U testuser -d testdb -c 'TRUNCATE TABLE users CASCADE;'");
139+
}
140+
```
141+
142+
---
143+
144+
## Combining Docker Terminal with SHAFT.API
145+
146+
Use Docker terminal commands to prepare the environment, then validate the results through the application API:
147+
148+
```java title="ContainerAndApiTest.java"
149+
import com.shaft.cli.TerminalActions;
150+
import com.shaft.driver.SHAFT;
151+
152+
@Test
153+
void createUserViaDbAndVerifyThroughApi() {
154+
// Insert a user directly into the database container
155+
TerminalActions db = new TerminalActions("postgres-db", "postgres");
156+
db.performTerminalCommand(
157+
"psql -U testuser -d testdb -c " +
158+
"\"INSERT INTO users (name, email) VALUES ('Test User', 'test@example.com');\""
159+
);
160+
161+
// Verify through the REST API
162+
SHAFT.API api = new SHAFT.API("https://api.example.com");
163+
api.get("/users?email=test@example.com")
164+
.setTargetStatusCode(200)
165+
.performRequest();
166+
167+
api.assertThatResponse()
168+
.extractedJsonValue("$[0].name")
169+
.isEqualTo("Test User")
170+
.withCustomReportMessage("Newly created user should be retrievable via the API")
171+
.perform();
172+
}
173+
```
174+
175+
---
176+
177+
## Best Practices
178+
179+
- **Use specific container names** — avoid relying on container IDs which change between runs; use named containers in your `docker-compose.yml`.
180+
- **Scope your user** — run as the least-privileged user that can execute the required commands.
181+
- **Capture and validate output** — always store command output in a variable and assert on it rather than ignoring the return value.
182+
- **Attach output as evidence** — use `SHAFT.Report.attach()` to include command output in the Allure report for traceability.
183+
- **Ensure idempotency** — teardown commands in `@AfterMethod` should be safe to run even if the test failed mid-way.
184+
185+
---
186+
187+
## Related Pages
188+
189+
- [Terminal Actions](./Terminal_Actions.md) — Local terminal execution overview and common patterns.
190+
- [SSH Remote Terminal](./SSH_Terminal.md) — Execute commands on remote servers via SSH.
191+
- [File Actions](./File_Actions.md) — Copy files between local and remote/container filesystems.

0 commit comments

Comments
 (0)